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

При автоматической инструментации библиотеки и агенты OpenTelemetry перехватывают вызовы стандартных фреймворков и протоколов и самостоятельно создают спаны. Вы получаете трассировку без написания дополнительного кода — достаточно подключить агент или библиотеку и указать параметры экспорта.

Принцип работыПринцип работы

Автоинструментация встраивается между вашим приложением и используемыми библиотеками. В зависимости от языка это работает по-разному:

• Java — Java-агент модифицирует байткод при загрузке классов.
• Python, Node.js — инструменты подменяют вызовы стандартных модулей на обертки, создающие спаны.

Во всех случаях каждый перехваченный вызов автоматически создает спан с атрибутами по семантическим конвенциям OpenTelemetry — HTTP-метод, URL, статус ответа, имя таблицы БД и т. д.

Что покрывается автоматическиЧто покрывается автоматически

Автоинструментация создает спаны для типовых операций:

• HTTP-серверы и клиенты (Flask, Django, Express, Spring, requests, net/http и др.)
• Клиенты баз данных (PostgreSQL, MySQL, Redis, MongoDB)
• Очереди сообщений (Kafka, RabbitMQ)

Полный список поддерживаемых библиотек для каждого языка см. в реестре инструментации OpenTelemetry.

Общие параметры подключенияОбщие параметры подключения

Независимо от языка, для отправки трейсов в Monium Traces укажите параметры подключения через переменные окружения:

export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"

export OTEL_SERVICE_NAME=<имя_приложения>

export OTEL_EXPORTER_OTLP_ENDPOINT="ingest.monium.yandex.cloud:443"

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Key <API-ключ>,x-monium-project=folder__<идентификатор_каталога>"

export OTEL_RESOURCE_ATTRIBUTES="cluster=<окружение>"

Где:

• OTEL_SERVICE_NAME — имя вашего приложения. Используется как значение service.name в атрибутах ресурса.
• OTEL_EXPORTER_OTLP_ENDPOINT — эндпоинт Monium.
• OTEL_EXPORTER_OTLP_HEADERS — заголовки авторизации и привязки к проекту. Для получения API-ключа создайте сервисный аккаунт с ролью monium.traces.writer и API-ключ с областью действия yc.monium.traces.write.
• OTEL_RESOURCE_ATTRIBUTES — атрибуты ресурса. cluster задает окружение (по умолчанию default).

Подключение по языкамПодключение по языкам

PythonPython

1. Установите дистрибутив OpenTelemetry и экспортер:

   pip install opentelemetry-distro opentelemetry-exporter-otlp
   

2. Установите инструментацию для библиотек, которые использует ваше приложение:

   opentelemetry-bootstrap -a install
   

   Команда автоматически определит установленные библиотеки (Flask, Django, requests, psycopg2 и др.) и установит соответствующие пакеты инструментации.

3. Запустите приложение через обертку opentelemetry-instrument:

   opentelemetry-instrument python my_app.py
   

JavaJava

1. Скачайте Java-агент OpenTelemetry:

   curl -L -o opentelemetry-javaagent.jar \
     https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
   

2. Запустите приложение с агентом:

   java -javaagent:opentelemetry-javaagent.jar -jar my_app.jar
   

   Агент автоматически инструментирует Spring, Servlet, JAX-RS, JDBC, Kafka, gRPC и другие библиотеки.

Node.jsNode.js

1. Установите пакет автоинструментации:

   npm install @opentelemetry/auto-instrumentations-node
   

2. Запустите приложение с автоматической регистрацией:

   node --require @opentelemetry/auto-instrumentations-node/register app.js
   

ОграниченияОграничения

Автоинструментация покрывает только операции, для которых существуют готовые библиотеки. Она не создает спаны для:

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

Для трассировки таких операций используйте ручную инструментацию.