</>
halfcoder

Гайды

OpenTelemetry: трассировка и observability

Трейсы, метрики и логи, OTLP и Collector, сэмплинг, корреляция с логами и интеграция с Prometheus.

~10 мин чтения

МониторингНаблюдаемостьOpenTelemetry

OpenTelemetry: трассировка и observability

OpenTelemetry — единый стандарт трассировок, метрик и логов: SDK в приложении экспортирует данные в OTLP, дальше — Jaeger, Tempo, Grafana Cloud, vendor APM. Связь с логами — ELK; k8s-метрики — Prometheus Operator.

1. Три столпа observability

СигналВопрос
TracesКакой путь запроса и где задержка?
MetricsКак система деградирует со временем?
LogsЧто произошло в момент события?

Корреляция через trace_id в логах.

2. Концепции трассировки

Span — один блок работы (HTTP-вызов, DB query). Trace — дерево span'ов. Context propagation (W3C TraceContext) передаёт traceparent между сервисами.

3. Python (FastAPI) — идея

opentelemetry-instrumentation-fastapi, Resource с service.name, TracerProvider + OTLP exporter (gRPC/HTTP). Автоинструментация vs ручные span'ы для критичных участков.

4. Экспортеры и бэкенд

OTLP → Collector → fan-out в Prometheus, Tempo, Loki. Collector даёт processors (batch, attributes, redact PII).

Минимальная идея otel-collector-config.yaml (упрощённо):

yaml
receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/tempo]

На практике добавляют batch processor, memory_limiter и отдельный pipeline для metrics/logs.

5. Sampling

Head-based (решение на старте trace) vs tail-based (на коллекторе после завершения — ловит редкие ошибки, дороже).

6. PII и секреты

Attribute redaction в Collector; не класть токены в span attributes.

7. Baggage и контекст

Baggage (W3C) переносит пары ключ–значение вместе с trace context — удобно для tenant-id, но не для PII (попадает в исходящие запросы). Разделяйте trace state и бизнес-метаданные осознанно.

8. Метрики и exemplars

OTel metrics SDK + экспорт в Prometheus OTLP endpoint; exemplars связывают гистограммы с trace_id для drill-down из Grafana в Tempo/Jaeger.

9. Переменные OTEL_* без правок кода

Часто достаточно задать в окружении OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_TRACES_EXPORTER=otlp, при необходимости OTEL_RESOURCE_ATTRIBUTES (deployment.environment=prod, service.version=1.4.2). Kubernetes: env в Pod или envFrom: configMapRef. Так поднимают auto-instrumentation до первого коммита в код; для sampling и кастомных span'ов всё равно понадобится конфигурация в приложении или в Collector.

10. Чек-лист

  • Единый service.name и версия деплоя в resource.
  • Инструментация исходящих HTTP и DB драйверов.
  • Дашборды p95 latency по маршрутам и зависимостям.
  • Бюджет на хранение трейсов (TTL).
  • Конфиг Collector в Git с ревью; версии exporter и backend согласованы.
  • Документированы обязательные OTEL_* для каждого окружения.

Дальше: Kibana · тег «Наблюдаемость»