## Зачем В монолите debug — это stacktrace. В микросервисах один запрос проходит через 5-50 сервисов, и у каждого свой stacktrace; склеить их руками невозможно. **Distributed tracing** склеивает их автоматически через `trace_id`, который протянут сквозь каждый hop. Без tracing вопрос «куда ушли 2.5 секунды?» решается часами корреляции дашбордов и догадок. С tracing — клик и waterfall, видно точно: «80% времени в Postgres call внутри svc-payment». ## Mental model > Trace — это **граф спанов**, где каждая span = «что-то делал N миллисекунд». `trace_id` связывает их через всю цепочку. Главная магия — **context propagation**: каждый сервис должен передать `trace_id` через HTTP-header / message metadata, иначе trace обрывается. 90% поломок tracing — пропущенный propagation в async-коде. Базовые сущности: - **Trace** — корневой span + все потомки. Один trace = один user request через всю систему. - **Span** — единица работы с временной меткой и длительностью (HTTP call, DB query, cache lookup). - **Trace ID** — 128-bit (W3C) или 64-bit (legacy), уникальный на trace. - **Span ID + Parent Span ID** — иерархия: child ссылается на parent. - **Span attributes / events** — статичные key-value vs точечные «что произошло внутри спана». - **Baggage** — key-value, propagates через всю trace (`user.tier=premium`, `tenant.id=...`). - **Span kind** — `SERVER`, `CLIENT`, `PRODUCER`, `CONSUMER`, `INTERNAL`. Стандартные заголовки (W3C Trace Context): ``` traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 tracestate: vendorname=value,othervendor=value baggage: user.tier=premium,region=eu ``` ## Что на диаграмме Четыре группы: **Edge** (LB, API Gateway), **Services** (Auth, Order, Inventory, Payment — все инструментированы OTel), **Data** (Postgres, Redis, Kafka), **Tracing pipeline** (OTel Collector → Tempo на S3 → Grafana). Edges делятся на два класса: - **Request path** — `user → lb → gw → services → data`, по нему течёт обычный трафик с `traceparent` в headers. - **Span export** — `services → otel → tempo`, отдельный side-channel: spans уезжают в Collector асинхронно по OTLP (gRPC), не блокируя hot path. Это ключевая мысль: tracing-трафик идёт **параллельно** бизнес-трафику и **не на критическом пути**. Если Collector ляжет — приложение продолжит работать, потеряются только spans. ## Сценарии ::scenario{key="propagation"} Edge gateway генерирует `trace_id` на root request, кладёт `traceparent` header. Каждый downstream service достаёт header, создаёт **child span** с тем же `trace_id` и новым `span_id`, ссылается на parent. Все spans уезжают в OTel Collector асинхронно — Grafana собирает их по `trace_id` в один waterfall. Семь спанов от одного запроса = одна полная картинка пути. ::scenario{key="tail-sampling"} Head sampler на edge решил «не сэмплируем» (99% случаев — экономим storage). Но при ошибке tail-collector в OTel **переопределяет** решение: видит `error=true` в одном из spans → сохраняет **весь** trace, даже если head его дропнул. То же для slow traces (`duration > p99`). On-call открывает Grafana, видит полный waterfall, root cause за минуту вместо часа. ::scenario{key="latency"} P99-алерт сработал: запрос занял 3.2 секунды. Инженер идёт в Grafana → Tempo, фильтрует `duration > 3s`, находит конкретный `trace_id`. Waterfall показывает: `auth=12ms, redis=2ms, pg=8ms, inventory=45ms, payment=2980ms`. Дрилл в payment span → внутри `http.client → stripe.com = 2.85s`. Root cause не в нашем коде — внешний API регрессировал. Тикет открыт Stripe-у за 2 минуты. ::scenario{key="broken-async"} Антипаттерн: сервис публикует в Kafka, **забывает** инжектить `traceparent` в headers сообщения. Consumer на другой стороне начинает **новый** root span с новым `trace_id`. Каузальная связь «produce → consume» **теряется** — в Grafana два разных trace, не связанных. Самая частая дыра в tracing: всегда `propagator.inject(ctx, headers)` перед publish. ## Trade-offs (ADR) Главная архитектурная развилка — **head- vs tail-based sampling** (ADR-001 в группе Services): | Подход | Плюсы | Минусы | |---|---|---| | **Head-based (1%)** | Дёшево, без памяти, решение на root | Пропускаешь редкие ошибки и slow traces — самое ценное | | **Tail-based** | Видишь все errors, все p99 slow | Stateful collector с памятью на ~30s буфер; HA нужна | | **Гибрид (выбран)** | Head 1% базовый + tail override на errors/slow | Сложнее эксплуатация, но <5% volume / >95% полезных traces | На 50K req/s полный 100%-sampling = ~50 GB/час storage (1KB/span × 20 spans/trace). Tail-collector буферизирует ~30 секунд spans в RAM — это десятки гигабайт памяти на узел при пиковых QPS, но при этом ловит 95%+ инцидентов. Второй важный trade-off — **auto vs manual instrumentation**: - Auto-агенты (Java agent, `opentelemetry-instrument` для Python, `--require` для Node) покрывают 80% — все HTTP/gRPC/JDBC/Kafka hops бесплатно. - Manual оборачивает только 5-10 ключевых бизнес-функций на сервис. Yuri Shkuro (создатель Jaeger) рекомендует именно Pareto-подход. Span на каждую `for`-итерацию = 100K spans в одном trace, UI ляжет. Третий — **backend choice**: | Backend | Сильные стороны | Слабости | |---|---|---| | **Jaeger** | OSS де-факто (Uber, eBay), CNCF graduated | UI устарел, query slow при scale | | **Tempo** | S3-backed, очень дёшево, LGTM-стек | Только trace, query через trace_id | | **Honeycomb** | Лучший UX, BubbleUp, wide-events | $$$, vendor lock-in | | **Datadog APM** | Корреляция с metrics/logs, лучший APM | $$$, vendor lock-in | | **AWS X-Ray** | Native в AWS, дёшево | Слабый UI, AWS lock-in | ## Реальные системы - **Uber / Jaeger (2015-2017):** 4000+ микросервисов, один trip request = ~50 services. Без tracing debug инцидента занимал дни. Jaeger построили внутри, open-sourced 2017, передали CNCF 2019, graduated 2021. - **Google Dapper (2010 paper):** оригинал концепции. Принцип «low-overhead»: tracing должен брать <1% CPU. Это привело к sampling-by-default и async export — паттерну, который повторили все. - **Cloudflare edge (2020):** 1/1000 baseline + keep all errors. 50M req/s → 50K trace/s в storage. Включили sampled tracing — нашли, что 30% origin slowness был у customers с одной конкретной WAF rule. Без tracing найти было бы невозможно. - **Honeycomb «Observability Engineering»:** high-cardinality span attributes (например `user_id` на каждом span — это **OK** в отличие от metrics!) позволяют BubbleUp анализ: «среди slow trace что общего? — все из `tier=enterprise + region=ap-south`». Один запрос за минуту. ## Anti-patterns - **100% sampling в prod.** Cost-катастрофа, storage линейно с трафиком. Head 1% + tail для errors/slow. - **No baggage propagation.** Теряется бизнес-контекст. Положи `user.tier`, `tenant.id` в baggage на edge — потом фильтруй traces по этим полям. - **Spans too granular.** Span на каждую функцию → 10K spans в одном trace. UI становится нечитаемым, storage стонет. Span на logical unit of work, не на function. - **Async код без context.** Самая частая дыра. Go-routine, Node promise, Kafka producer-consumer — все теряют context, если ты явно не передал. В Go: всегда `ctx context.Context` первым аргументом; в Node: async hooks / OTel auto-instrumentation; в Kafka/RabbitMQ: `propagator.inject(headers)` перед publish. - **Sensitive data в span attributes.** Credit card в `db.statement`, auth token в `http.url`. Та же security-проблема, что и с logs. Используй OTel processor для маскинга на Collector. - **Tracing без metrics.** Нет агрегатов — нельзя алертить. Span metrics (RED) автоматически выводят latency/errors из spans (Tempo metrics generator, Jaeger SPM). - **Один tracing backend для dev/staging/prod.** Dev-шум топит prod-сигнал. Отдельные backends или хотя бы namespaces. - **Свои headers вместо W3C Trace Context.** Несовместимость с любым другим инструментом. Не изобретай — `traceparent` стандарт с 2020. ## Когда НЕ использовать - **Монолит без сетевых hops.** Stacktrace + profiler покрывают 95% кейсов. Tracing добавит overhead без отдачи. - **Batch / cron-задачи.** Если задача длится час и обрабатывает миллион записей, span на каждую = взрыв storage. Лучше logs + metrics + per-batch span с агрегатами. - **Команда < 5 человек, < 5 сервисов.** Overhead на инструментацию и Collector эксплуатацию выше ROI. Подожди до 10+ сервисов или первого многочасового инцидента. - **Жёсткие latency-SLO < 1ms.** Auto-инструментация добавляет 50-200μs на hop. Для HFT или некоторых ad-tech это уже много — придётся selective manual instrumentation. - **Compliance запрещает любую корреляцию.** Редкий случай (GDPR-параноя на максималках), но `trace_id` в логах = linkability. Решение: separate trace stream без PII. ## Дальше читать - **Yuri Shkuro — «Mastering Distributed Tracing»** (Packt, 2019). Автор Jaeger, лучшая книга на тему. - **Google Dapper paper (2010):** — оригинал, читается до сих пор. - **OpenTelemetry concepts:** - **W3C Trace Context spec:** - **Charity Majors — observability retrospective:** - **Grafana Tempo docs:** — для S3-backed cheap tracing. - **CNCF Jaeger docs:** - Связанные концепты: ::concept{slug="observability-pillars"}, ::concept{slug="golden-signals-deep"}