Auto-instrumentation
Тема дорожной карты · Observability
Автоинструментирование — это возможность добавить наблюдаемость OpenTelemetry в приложение без изменения его исходного кода путём внедрения агентов инструментирования при запуске или через мутирующий вебхук Kubernetes. Для Java-приложений opentelemetry-javaagent.jar подключается к JVM и автоматически инструментирует популярные фреймворки (Spring, gRPC, JDBC и другие); для Python запуск opentelemetry-instrument python app.py оборачивает приложение; для Node.js флаг --require @opentelemetry/auto-instrumentations-node/register активирует автоинструментирование. Автоинструментирование из коробки генерирует распределённые трассировки, метрики и логи для HTTP-запросов, запросов к базам данных и операций с очередями сообщений, что значительно снижает порог входа в наблюдаемость для существующих кодовых баз. Переменные окружения OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME и OTEL_TRACES_SAMPLER управляют поведением автоинструментирования без изменений в коде. В Kubernetes-окружениях OpenTelemetry Operator может автоматически внедрять подходящий агент автоинструментирования в поды на основе аннотаций кастомного ресурса Instrumentation.
Как это работает
Auto-instrumentation (OTel) — vendor-neutral стандарт инструментирования. Спеки покрывают API + SDK + протокол (OTLP — gRPC или HTTP). Auto-instrumentation библиотеки — для популярных фреймворков. OTel Collector — sidecar/daemon, принимающий OTLP + роутящий в backends (Prometheus, Loki, Tempo, Jaeger, vendor API). Один API + SDK для метрик, логов, traces. Поддерживается CNCF, принят AWS, Google, Microsoft, Datadog, Splunk, Yandex.
Когда применять
OpenTelemetry — для любого нового проекта; нет причин запираться в vendor SDK. Auto-instrumentation сначала (покрывает 80% без изменения кода). Collector — для централизации роутинга; смена backend без переинструментирования приложений. Для метрик OTel может заменить Prometheus client libs или кормить Prometheus через OTLP-receiver; оба работают.
Типичные ошибки
Ловушки Auto-instrumentation: ручное инструментирование, когда сработала бы auto-instrumentation (DRY + баги); запуск Collector с дефолт-конфигом во внутренний API production (нет auth + TLS — защитите); pre-OTel и post-OTel SDK в одном проекте (путано, хрупко); не выставлены resources service.name + service.version (traces без provenance).