OpenTelemetry

01Три сигнала и как они связаны

Телеметрия бывает трёх основных видов (сигналов). Трейс — это история одного запроса: дерево спанов, где каждый span — одна единица работы (HTTP-обработчик, SQL-запрос, вызов платёжного API) со временем начала, длительностью, статусом и атрибутами вроде http.route или db.system. Метрики — числовые измерения, агрегированные во времени: частота запросов, доля ошибок, гистограммы задержек, глубина очереди, память. Их дёшево хранить, и они отлично подходят для дашбордов и алертов. Логи — записи о событиях с временными метками. Сила OpenTelemetry — в корреляции: логи, записанные внутри спана, несут его trace ID и span ID, а метрики могут нести exemplars со ссылками на примерные трейсы. Так алерт по p95-задержке приводит вас к медленному трейсу, а трейс — к точным строкам логов. Трейсы, метрики и логи в спецификации стабильны; профилирование добавляется как четвёртый сигнал.

• Трейс = дерево спанов для одного запроса.
• Метрики = дешёвые агрегаты для алертов и дашбордов.
• Логи = события, связанные через trace ID и span ID.

02Архитектура: API, SDK, экспортёры и Collector

OTel чётко разделяет обязанности. API — это то, что вызывают библиотеки и ваш код, чтобы создавать спаны и записывать метрики; сам по себе он ничего не делает, поэтому библиотеки могут безопасно от него зависеть. SDK — реализация, которую вы настраиваете в приложении: он решает, что сэмплировать, собирает данные в батчи и передаёт экспортёрам. Экспортёры отправляют данные наружу, обычно по OTLP (OpenTelemetry Protocol), на порт 4317 для gRPC или 4318 для HTTP. Библиотеки инструментации патчат популярные фреймворки и клиенты (Express, Fastify, Next.js, Laravel, pg, mysql, Redis, HTTP-клиенты), чтобы создавать спаны автоматически. Collector — отдельный сервис, который принимает телеметрию, обрабатывает её (батчинг, фильтрация, удаление чувствительных атрибутов, сэмплирование) и экспортирует в один или несколько бэкендов. Его можно запускать как агент рядом с каждым приложением, как центральный шлюз или и так и так. Ресурсы описывают, кто отправил данные: service.name, service.version, deployment.environment.name.

03Инструментация сервиса на Node.js

Быстрее всего начать в Node.js с SDK и набора автоинструментаций. Установите @opentelemetry/sdk-node, @opentelemetry/auto-instrumentations-node и OTLP-экспортёр, затем подгрузите небольшой файл настройки до кода приложения — для ES-модулей через node --import. Настраивайте через стандартные переменные окружения, а не захардкоженные значения, чтобы один и тот же образ работал во всех окружениях: OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_RESOURCE_ATTRIBUTES и OTEL_TRACES_SAMPLER. В Next.js есть встроенный хук instrumentation.ts и хелпер @vercel/otel. Laravel и PHP используют расширение OpenTelemetry для PHP плюс пакеты автоинструментации. Начните с автоинструментации, посмотрите на реальные трейсы, а затем добавляйте свои спаны только вокруг важных бизнес-шагов.

1// instrumentation.mjs: run with  node --import ./instrumentation.mjs server.mjs
2import { NodeSDK } from "@opentelemetry/sdk-node";
3import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
4import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
5import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
6import { PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
7 
8// Endpoint and service name come from OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_SERVICE_NAME
9const sdk = new NodeSDK({
10  traceExporter: new OTLPTraceExporter(),
11  metricReader: new PeriodicExportingMetricReader({ exporter: new OTLPMetricExporter() }),
12  instrumentations: [getNodeAutoInstrumentations({ "@opentelemetry/instrumentation-fs": { enabled: false } })],
13});
14 
15sdk.start();
16process.on("SIGTERM", () => sdk.shutdown().finally(() => process.exit(0)));

04Свои спаны и атрибуты

Автоинструментация показывает HTTP-вызовы и обращения к базе, но не вашу бизнес-логику. Добавьте span вокруг значимых шагов вроде «расчёт цены», «резервирование товара» или «генерация PDF-счёта» и прикрепите атрибуты, которые помогут потом искать: order.items_count, tenant.tier, cache.hit. Для распространённых имён следуйте semantic conventions (http.request.method, db.system.name, messaging.system), чтобы бэкенды их понимали. Помните о кардинальности атрибутов: ID заказа на спане — нормально, ведь span — это одно событие, но никогда не кладите ID пользователей или URL с ID в атрибуты метрик, потому что каждое уникальное значение создаёт новый временной ряд. Записывайте исключения в span и выставляйте статус ошибки, чтобы неудачные запросы легко находились. Никогда не кладите в атрибуты пароли, токены или полные номера карт.

1import { trace, SpanStatusCode } from "@opentelemetry/api";
2 
3const tracer = trace.getTracer("checkout");
4 
5export async function placeOrder(cart: { items: unknown[] }) {
6  return tracer.startActiveSpan("checkout.place_order", async (span) => {
7    span.setAttribute("order.items_count", cart.items.length);
8    try {
9      const order = await saveOrder(cart); // pg / HTTP calls become child spans
10      span.setAttribute("order.id", order.id);
11      return order;
12    } catch (err) {
13      span.recordException(err as Error);
14      span.setStatus({ code: SpanStatusCode.ERROR });
15      throw err;
16    } finally {
17      span.end();
18    }
19  });
20}

05Запуск Collector

Отправлять телеметрию из приложений прямо вендору можно, но Collector посередине даёт контроль. Приложения быстро отправляют OTLP в локальный Collector и возвращаются к работе; Collector собирает батчи, повторяет отправку и буферизует, если бэкенд тормозит, так что приложение не страдает. Это правильное место, чтобы добавить атрибуты окружения, отбросить шумные спаны вроде health checks, удалить чувствительные данные и применить tail sampling. Он также умеет собирать метрики Prometheus и читать файлы логов, становясь вашим единым конвейером телеметрии. Используйте contrib-дистрибутив (otelcol-contrib) для полного набора процессоров и экспортёров или соберите минимальный с помощью OpenTelemetry Collector Builder. В каждом пайплайне всегда ставьте процессор memory_limiter первым, а batch — последним, и следите за собственными метриками Collector на предмет потерянных данных.

1# otel-collector.yaml
2receivers:
3  otlp:
4    protocols:
5      grpc: { endpoint: 0.0.0.0:4317 }
6      http: { endpoint: 0.0.0.0:4318 }
7processors:
8  memory_limiter: { check_interval: 1s, limit_percentage: 80, spike_limit_percentage: 20 }
9  attributes/scrub:
10    actions: [{ key: http.request.header.authorization, action: delete }]
11  batch: {}
12exporters:
13  otlphttp: { endpoint: https://otlp.example.com }
14service:
15  pipelines:
16    traces: { receivers: [otlp], processors: [memory_limiter, attributes/scrub, batch], exporters: [otlphttp] }
17    metrics: { receivers: [otlp], processors: [memory_limiter, batch], exporters: [otlphttp] }

06Tail sampling в масштабе

Tail sampling сохраняет трейсы целиком в зависимости от того, что в них произошло, но спаны одного трейса приходят из многих сервисов в разное время. Collector держит спаны в памяти в течение периода ожидания решения (часто 10–30 секунд), а затем применяет политики: status_code ERROR, задержка выше порога, конкретные атрибуты или вероятностная доля для остальных. При нескольких репликах Collector все спаны одного трейса должны попасть в один инстанс, поэтому запускают два уровня: агенты или первый шлюзовой слой с load-balancing-экспортёром по ключу trace ID, а за ними — слой сэмплирования. Рассчитывайте память как трафик × время ожидания и следите за метриками процессора по отброшенным трейсам. Помните, что отброшенные при сэмплировании трейсы влияют и на метрики, построенные из спанов; генерируйте RED-метрики (rate, errors, duration) коннектором spanmetrics до сэмплирования, чтобы дашборды оставались точными.

1processors:
2  tail_sampling:
3    decision_wait: 15s
4    num_traces: 100000
5    policies:
6      - { name: errors, type: status_code, status_code: { status_codes: [ERROR] } }
7      - { name: slow, type: latency, latency: { threshold_ms: 1000 } }
8      - { name: baseline, type: probabilistic, probabilistic: { sampling_percentage: 5 } }

07Распространение контекста через очереди и асинхронную работу

Автоматическое распространение покрывает синхронные HTTP и gRPC. С асинхронной работой нужна аккуратность. Когда вы публикуете задачу в Redis, RabbitMQ или Kafka, встраивайте активный контекст в заголовки сообщения; когда воркер её забирает, извлекайте контекст и начинайте consumer-span. Semantic conventions моделируют это через виды спанов producer и consumer. Сильно отложенная задача ставит вопрос дизайна: должны ли её спаны быть дочерними к запросу, который её создал? Для коротких конвейеров — да, но задача, выполняемая через час, даёт странный, очень длинный трейс. Альтернатива — новый трейс со span link на исходный контекст: связь сохраняется, а трейс не растягивается. Пакетные потребители должны использовать ссылки на множество контекстов producer-ов. Baggage может переносить между сервисами значения вроде tenant ID, но он отправляется с каждым запросом, поэтому держите его маленьким и никогда не кладите туда секреты.

1import { context, propagation, trace } from "@opentelemetry/api";
2 
3// Producer: carry the trace context inside the job payload
4export function withTraceHeaders<T extends object>(payload: T) {
5  const headers: Record<string, string> = {};
6  propagation.inject(context.active(), headers);
7  return { ...payload, otel: headers };
8}
9 
10// Consumer: continue the trace when the job runs
11export function runJob(job: { otel?: Record<string, string> }, work: () => Promise<void>) {
12  const parent = propagation.extract(context.active(), job.otel ?? {});
13  return context.with(parent, () =>
14    trace.getTracer("worker").startActiveSpan("job.process", (span) => work().finally(() => span.end())),
15  );
16}

08Дизайн метрик: инструменты, temporality и кардинальность

Метрики OTel используют инструменты: Counter для того, что только растёт (запросы, отправленные байты), UpDownCounter для значений, которые растут и падают (размер очереди, активные соединения), Histogram для распределений (задержка, размер payload) и Gauge для снимков текущих значений. Именно гистограммы дают p95 и p99; экспоненциальные гистограммы обеспечивают хорошую точность при меньшем числе бакетов. Temporality важна при экспорте: бэкенды в стиле Prometheus ожидают кумулятивные значения, а некоторые вендоры предпочитают delta, и экспортёр можно настроить в любую сторону. Кардинальность — главный драйвер стоимости: каждая уникальная комбинация значений атрибутов — отдельный временной ряд. http.route=/orders/:id — нормально; «сырой» URL /orders/123 — катастрофа. Используйте views, чтобы отбрасывать или переименовывать атрибуты и менять бакеты гистограмм, не трогая код инструментации.

09Накладные расходы, безопасность и поэтапное внедрение

Инструментация не бесплатна, но обычно её цена мала: несколько процентов CPU, в основном на создание и экспорт спанов. Держите её низкой с помощью batch span processor (никогда не simple processor в продакшене), сэмплирования и отключения шумных инструментаций вроде спанов файловой системы или DNS. Экспорт никогда не должен блокировать запросы: если бэкенд недоступен, SDK отбрасывает данные после заполнения очереди, а не замедляет приложение. Очищайте чувствительные данные на двух уровнях: не собирайте их в коде и удаляйте заголовки, query-строки и SQL-параметры в Collector. Внедряйте посервисно, начиная с edge и самого критичного пути, и сравнивайте задержку до и после. Относитесь к Collector как к продакшен-инфраструктуре: health checks, лимиты ресурсов, горизонтальное масштабирование и алерты на потерянные спаны.