Автоинструментирование и семантические конвенции

80% спанов должны появляться без вашего кода: HTTP, gRPC, SQL, Redis, Kafka — всё инструментируется библиотеками OpenTelemetry. А чтобы трейсы были одинаковыми во всех сервисах, существуют семантические конвенции.

Три способа инструментировать

Автоинструментирование по языкам

# Python: общий агент
opentelemetry-instrument --traces_exporter otlp python app.py
# конкретные инструменты: opentelemetry-instrumentation-fastapi, -requests, -sqlalchemy, -redis, -kafka-python ...

# Java: агент одной jar-кой
java -javaagent:opentelemetry-javaagent.jar -jar app.jar
# инструментирует JDBC, Tomcat/Spring, gRPC, Kafka, Redisson, OkHttp... из коробки

# Node.js
node --import ./instrumentation.ts app.js
# @opentelemetry/auto-instrumentations-node: http, express, pg, redis, amqplib...

# .NET
OTEL_DOTNET_AUTO_HOME=... dotnet run
# или NuGet-пакеты OpenTelemetry.Instrumentation.*

Настройка — те же переменные среды (endpoint, service name, сэмплер). Java-агент плюс Java-специфика: -Dotel.exporter.otlp.endpoint=....

⚠️ Автоинструментирование — это не «включил и забыл» навсегда: обновление агента может изменить набор спанов, а тяжёлые агенты имеют цену старта и памяти. Но для HTTP/БД/ кеша это лучший первый шаг.

Что даёт каждая библиотека (типовые спаны)

• HTTP-сервер: GET /orders + атрибуты метод, маршрут, статус;
• HTTP-клиент: спан исходящего вызова + дожим заголовка traceparent;
• SQL (jdbc/sqlalchemy/pg): SELECT orders + db.system=postgresql, db.statement (внимание: см. PII ниже);
• Redis: GET/SET + db.redis.database_index;
• Kafka: продюсер/консюмер-спаны + контекст в заголовках сообщений.

Семантические конвенции — общий язык

Если один сервис пишет http.method, а другой http_verb, поиск и дашборды ломаются. Конвенции OTel фиксируют имена и значения:

💡 http.route (шаблон маршрута /orders/{id}, а не реальный URL) — критично: спанов с полным URL будет миллион уникальных имён, а с route — десяток. Хорошие библиотеки заполняют route сами; в своих спанах соблюдайте это правило тоже.

Осторожно: данные в трейсах

Автоинструментирование может притащить db.statement с персональными данными, заголовки с токенами, полный URL с query-параметрами. Правила:

• Отключайте полные statements, если политика запрещает (OTEL_INSTRUMENTATION_<LIB>_DB_STATEMENT_SANITIZATION_ENABLED и аналоги);
• Маскируйте на Collector (processor transform/redaction) — модуль 3;
• Никогда не кладите в атрибуты: пароли, токены, номер карты, полный адрес, содержимое переписки.

Практика

1. Включите автоинструментирование в своём языке для HTTP + SQL (или Redis). Сравните список операций сервиса до/после.
2. Найдите в UI спан SQL-запроса: какие атрибуты есть, есть ли db.statement, есть ли в нём персональные данные.
3. Проверьте имена операций: все ли с низкой карточностью? Если есть URL с id — настройте маршрут-шаблоны.
4. Прочитайте страницу OTel Semantic Conventions для HTTP и выпишите 5 атрибутов, которые намерены использовать в дашбордах.