Авто-инструментирование и ручные спаны: правило 80/20 в OTel

Авто-инструментирование: 70-80%, которые вы получаете бесплатно

К концу урока ты будешь знать, куда именно добавить спан, когда трасса говорит «800 мс, 5 запросов в БД» — но не объясняет почему.

Большая часть production-трафика проходит через небольшой набор фреймворков — HTTP-серверы, HTTP-клиенты, драйверы БД, клиенты очередей — которые contrib-библиотеки OTel инструментируют из коробки.

Java: OTel Java Agent (-javaagent JAR) перезаписывает байткод при старте JVM и автоматически инструментирует ~200 библиотек — никаких изменений кода не требуется. Добавьте один флаг -javaagent к JVM-аргументам, задайте переменные окружения OTEL_SERVICE_NAME и OTEL_EXPORTER_OTLP_ENDPOINT, и каждый HTTP-запрос, JDBC-запрос и Kafka-сообщение будет трассирован.

Python: opentelemetry-instrument оборачивает процесс и monkey-patching применяет изменения к популярным библиотекам (Flask, Django, FastAPI, SQLAlchemy, Redis, Celery и др.).

Node.js: @opentelemetry/sdk-node плюс набор инструментаций (express, http, pg, redis, kafkajs), зарегистрированных до любых других импортов через require hook.

Go: Авто-инструментирование менее зрелое, поскольку в Go нет monkey-patching (техники подмены методов во время выполнения без изменения исходного кода). Авто-инструментирование на основе eBPF (через uprobes) — развивающийся подход; contrib-библиотеки OTel для Go требуют явной настройки middleware для каждого фреймворка.

70-80% — простая часть: HTTP-маршруты, запросы в БД, вызовы кэша, взаимодействие с очередями. Авто-инструментирование говорит вам что произошло. Ручное инструментирование говорит почему.

Ручное инструментирование: мост к диагностической ценности

Оставшиеся 20-30% — бизнес-специфичные спаны, кастомные атрибуты и сквозные концерны — здесь живёт настоящая диагностическая ценность, потому что именно здесь живут бизнес-вопросы.

Паттерн: откройте спан вокруг бизнес-операции, прикрепите атрибуты, описывающие операцию, и генерируйте span events для значимых моментов.

const span = tracer.startSpan("fraud.check", {
  attributes: {
    "customer.segment": customer.segment,
    "order.value_cents": order.valueCents,
    "feature_flag.fraud_model": flags.fraudModel,
  },
});

try {
  for (const rule of rules) {
    const result = await rules.engine.evaluate(rule, order);
    span.addEvent("rule.evaluated", {
      "rule.id": rule.id,
      "rule.result": result.outcome,
      "rule.latency_ms": result.latencyMs,
    });
  }
} catch (err) {
  span.recordException(err);
  span.setStatus({ code: SpanStatusCode.ERROR });
} finally {
  span.end();
}

Этот спан сообщает о сегменте клиента, стоимости заказа, состоянии фича-флага модели проверки мошенничества и результате каждой оценки правила — данные, которые авто-инструментирование не может видеть, поскольку не знает вашего бизнес-домена.

Паттерн платформенной обёртки

Ручное инструментирование — это один и тот же паттерн во всех сервисах, поэтому платформенные команды публикуют тонкую вспомогательную библиотеку, оборачивающую OTel API с организационными конвенциями:

• Типизированные бизнес-атрибуты — предопределённые имена атрибутов для общих концептов (сегмент клиента, состояние фича-флага, размер батча), чтобы команды не могли сделать опечатки.
• Хелперы редактирования — удаление PII перед прикреплением к спанам (email → хэш, SSN → маска).
• Хелперы span events — типизированные хелперы для типовых событий (cache miss, retry, fallback).
• Предварительная конфигурация Resource — имя сервиса, версия и окружение развёртывания из стандартизированного набора переменных окружения.

Новые сервисы импортируют обёртку; CI-линтер отклоняет прямое использование OTel SDK в новом коде (для предотвращения неконтролируемых имён атрибутов). Хуки переопределения позволяют командам добавлять специфичные для сервиса атрибуты без изменения обёртки.