Трассировки OpenTelemetry с помощью ЕдиногоАгента

Материал из Документация Ключ-АСТРОМ

Модули кода Ключ-АСТРОМ ЕдиныйАгент для Java, .NET, PHP, Python, Node.js и Go автоматически собирают данные о интервалах OpenTelemetry и интегрируют их в сквозные распределенные трассировки.

Модуль кода ЕдиногоАгента позволяет вам:

  • Получать представление о сторонних библиотеках или фреймворках, которые изначально не поддерживаются ЕдинымАгентом, но поставляются с предварительным инструментарием OpenTelemetry.
  • Расширять данные мониторинга с помощью дополнений, специфичных для проекта (например, специализированного инструментария, который добавляет бизнес-данные или собирает диагностические точки, специфичные для разработчика).
  • Объединять независимые, несвязанные транзакции, чтобы расширить сквозные трассировки (например, добавляя нейтральные по отношению к поставщику пользовательские инструменты для получения сквозных сведений о транзакциях, специфичных для бизнес-процесса или домена).

Качество диапазонов OpenTelemetry, захватываемых ЕдинымАгентом, зависит от качества инструментария, предоставляемого сторонней библиотекой.

Требования

Java

Структура мониторинга Версии
OpenTelemetry 1,0 - 1,31 ,1,4 - 1,541
OpenTracing 0,33,0,32,0,31

1 Поддерживается в AWS Lambda.

Go

Структура мониторинга Версии
OpenTelemetry 1,0 - 1,7,1.8 - 1.11.0,1.11.1 - 1.27,1.28 - 1.38

Node.js

Структура мониторинга Версии
OpenTelemetry 11

1 Поддерживается в AWS Lambda.

PHP

Структура мониторинга Версии
OpenTelemetry 1.0.0

.NET and .NET Core

Структура мониторинга Версии
OpenTelemetry 1.0.1+,1.1+

.NET Framework

Структура мониторинга Версии
OpenTelemetry 1.0.1+,1.1+

Python

Структура мониторинга Версии
OpenTelemetry 1.1+

Включение интеграции OpenTelemetry в кодовом модуле ЕдиногоАгента

ЕдиныйАгента автоматически подключается к трассировкам, полученным с помощью пользовательского или предварительного инструментария OpenTelemetry, и отправляет данные телеметрии на платформу Ключ-АСТРОМ.

За исключением Java (где эта функция включена по умолчанию), автоматическое получение трассировок OpenTelemetry в настоящее время является дополнительной функцией и должно быть специально включено пользователем, чтобы ЕдиныйАгент мог получать трассировки со следующих платформ:

  • Go
  • .NET
  • Node.js
  • PHP
  • Python

OpenTelemetry Java

Чтобы включить OpenTelemetry Java

  1. Перейдите в Настройки > Предпочтения > Функции ЕдиногоАгента.
  2. Найдите и включите OpenTelemetry (Java).

Существующие трассировщики заменяются и больше не будут работать после включения OpenTelemetry Java.

OpenTelemetry Go

Чтобы включить OpenTelemetry Go

  1. Перейдите в Настройки > Предпочтения > Функции ЕдиногоАгента.
  2. Найдите и включите OpenTelemetry (Go).

Для ЕдиногоАгента версии 1.217 и более ранних версий датчик OpenTelemetry Go распространяет контекст Ключ-АСТРОМ между процессами только в том случае, если включена опция Send W3C Trace Context HTTP-заголовков.

  1. Перейдите в Настройки > Предпочтения > Функции ЕдиногоАгента.
  2. Включите опцию Отправлять заголовки HTTP контекста трассировки W3C.

Существующие трассировки не подвержены влиянию поддержки ЕдиногоАгента OpenTelemetry for Go.

OpenTelemetry Node.js

Чтобы включить OpenTelemetry Node.js

  1. Перейдите в Настройки > Предпочтения > Функции ЕдиногоАгента.
  2. Найдите и включите OpenTelemetry (Node.js).

OpenTelemetry PHP

Чтобы включить OpenTelemetry PHP

  1. Перейдите в Настройки > Предпочтения > Функции ЕдиногоАгента.
  2. Найдите и включите OpenTelemetry (PHP).

Существующие трассировки не подвержены влиянию поддержки ЕдиногоАгента OpenTelemetry для PHP.

OpenTelemetry .NET

Чтобы включить OpenTelemetry .NET

  1. Перейдите в Настройки > Предпочтения > Функции ЕдиногоАгента.
  2. Найдите и включите OpenTelemetry (.NET).

Существующие трассировки не подвержены влиянию поддержки ЕдиногоАгента OpenTelemetry для .NET.

OpenTelemetry Python

Чтобы включить OpenTelemetry Python

  1. Перейдите в Настройки > Предпочтения > Функции ЕдиногоАгента.
  2. Найдите и включите OpenTelemetry (Python).

Существующие трассировки не подвержены влиянию поддержки ЕдиногоАгента OpenTelemetry для Python.

Различия между захватом ЕдиногоАгента и экспортом OTLP

Оба подхода, автоматический захват данных с помощью ЕдиногоАгента и экспорт через OTLP, преследуют примерно одну и ту же цель — отправку трассировок и их диапазонов в Ключ-АСТРОМ, но между ними есть небольшие различия. Они в первую очередь касаются следующих областей:

  • Как интервалы фиксируются и передаются в Ключ-АСТРОМ.
  • Что считается периодом входа и как он обрабатывается.
  • Иерархия промежутков.
  • Обработка любых возможных присутствующих атрибутов.

Точка внедрения

Одно из основных различий между приемом данных через ЕдиныйАгент и экспортом через OTLP заключается в точке приема данных. При экспорте через OTLP экспортер отправляет информацию о диапазоне в бэкенд только после завершения диапазона.

ЕдиныйАгент, с другой стороны, получает информацию о диапазоне в момент его создания и анализа ЕдинымАгентом. Поскольку этот объект диапазона может содержать только предварительную информацию, ЕдиныйАгент будет постоянно обновлять бэкенд о любых изменениях диапазона, происходящих на протяжении всего процесса трассировки.

Точки входа

Ещё одно отличие заключается в обработке интервалов точек входа (первый интервал трассировки). Во избежание возможных конфликтов с существующими трассировками PurePath, ЕдиныйАгент по умолчанию принимает только интервалы с типом интервала Server или Consumer. Обычно это не является проблемой, поскольку библиотеки инструментирования обычно настраивают соответствующий тип интервала, однако это следует учитывать, если ваше приложение полностью использует ручное инструментирование.

Это поведение можно настроить с помощью правила точки входа. Для этого в Ключ-АСТРОМ перейдите в раздел Настройки > Мониторинг сервисов > Точки входа в Span и создайте новое правило с соответствующим действием и записью сопоставления.

Image4054.png

Иерархия охвата

В зависимости от настроек вы также можете столкнуться с «обогащением плоских интервалов». Это происходит, когда интервалы отображаются в Ключ-АСТРОМ в виде плоского списка, а не древовидной иерархии. Хотя это, как правило, является поведением по умолчанию при использовании ЕдининымАгентом трассировок OpenTelemetry, иерархия может по-прежнему отражать фактические отношения интервалов, определенные инструментированием, в зависимости от задействованных модулей кода ЕдиногоАгента и их поддержки инструментируемых технологий.

Объединение диапазонов

При объединении диапазонов OpenTelemetry с трассировками датчиков ЕдиногоАгента убедитесь, что диапазоны OpenTelemetry являются конечными диапазонами, а не промежуточными диапазонами ЕдиногоАгента.

Сбор атрибутов

Поскольку ЕдиныйАгент принимает интервалы сразу после их создания, не все атрибуты могут присутствовать при первоначальном приеме. Любые атрибуты, добавленные позднее, выделяются в Ключ-АСТРОМ примечанием initial value not set и не могут быть использованы для правил захвата интервалов, поскольку они ещё не были доступны на момент оценки правил.

Image4055.png

Распространение контекста

При автоматическом приеме трассировок OpenTelemetry с помощью сенсора ЕдиногоАгента существует разница между распространением контекста трассировок OpenTelemetry и трассировок ЕдиногоАгента.

Хотя ваше приложение может уже корректно обрабатывать распространение трассировок OpenTelemetry, важно также объединить их с трассировкой ЕдиногоАгента. Этого можно добиться с помощью правила распространения контекста. Чтобы настроить это, в Ключ-АСТРОМ перейдите в раздел Настройки > Мониторинг сервисов > Распространение контекста Span и создайте правило распространения контекста Propagate с действием и записью сопоставления для рассматриваемого диапазона (например, на основе имени диапазона или библиотеки инструментирования).

Image4057.png

Постарайтесь избегать объединения трассировок для технологий, уже изначально охватываемых датчиками ЕдиногоАгента. Объединение таких областей OpenTelemetry в трассировку ЕдиногоАгента может привести к неопределённым состояниям.

Экспорт в сторонние бэкэнды с использованием ЕдиногоАгента

Хотя трассировки OpenTelemetry всегда экспортируются в другие бэкенды в исходном виде, при запуске новой трассировки OpenTelemetry приложением, управляемым ЕдинымАгентом, происходит небольшая корректировка данных. Это относится только к новым трассировкам, а не к трассировкам, продолжающимся через распространение контекста.

В этом случае ЕдиныйАгент мог уже создать новый объект трассировки при инициализации OpenTelemetry. Если эти две трассировки (с разными идентификаторами) не согласованы, данные телеметрии могут дублироваться или фрагментироваться. Чтобы избежать этого и при этом обеспечить согласованность трассировок Ключ-АСТРОМ PurePath, ЕдиныйАгент использует следующий подход:

  • Идентификатор трассировки OpenTelemetry имеет приоритет при экспорте третьим лицам.
  • На сервере Ключ-АСТРОМ вместо этого назначается идентификатор трассировки PurePath.

Чтобы обеспечить корреляцию между этими двумя идентификаторами, Ключ-АСТРОМ создает дополнительные ссылки для каждого диапазона, ссылаясь на трассировку OpenTelemetry.

Переопределение идентификатора применяется только к вновь запущенным трассировкам (не к распространению контекста) и к пакетам SDK OpenTelemetry для Go, Java, JavaScript, PHP и Python, но не к .NET.

Ограничения

Java

  • В версиях до 1.259 ЕдиныйАгент заменяет установленные глобальные компоненты OpenTelemetry SDK TracerProvider, Propagator и ContextManager. Поэтому при включении OpenTelemetry Java трассировки больше не отображаются этим SDK и не экспортируются в бэкенды, такие как Jaeger.
  • ЕдиныйАгент версии 1.259+ Чтобы избежать дубликатов, ЕдиныйАгент будет игнорировать интервалы из некоторых библиотек автоматического инструментирования.
  • Если для одной и той же технологии используются как датчики ЕдиногоАгента, так и датчики OpenTelemetry, могут возникнуть дополнительные накладные расходы.

Go

  • ЕдиныйАгент может инструментировать только реализацию Tracer стандартного OpenTelemetry SDK.
  • При наличии датчиков ЕдиногоАгента и OpenTelemetry для одной и той же технологии могут возникнуть следующие ограничения:
    • Дублирующиеся узлы в распределенных трассировках
    • Дополнительные накладные расходы

Node.js

  • В версиях до 1.261 ЕдиныйАгент заменяет установленные глобальные компоненты OpenTelemetry SDK TracerProvider, Propagator и ContextManager. Поэтому при включении OpenTelemetry Node.js трассировки больше не отображаются этим SDK и не экспортируются в бэкенды, такие как Jaeger.
  • Когда ЕдиныйАгент и OpenTelemetry используют один и тот же модуль (например, HTTP или GRPC), вы можете столкнуться со следующими ограничениями:
    • Дублирующиеся узлы в распределенных трассировках
    • Разъединенные распределенные трассы
    • Дополнительные накладные расходы

PHP

  • ЕдиныйАГент версии 1.313+ Чтобы избежать дубликатов, ЕдиныйАгент будет игнорировать интервалы из некоторых библиотек автоматического инструментирования .

Python

  • При наличии датчиков ЕдиногоАгента и OpenTelemetry для одной и той же технологии могут возникнуть следующие ограничения:
    • Дублирующиеся узлы в распределенных трассировках
    • Разъединенные распределенные трассировки
    • Дополнительные накладные расходы

Все языки

  • ЕдиныйАгент захватывает атрибуты ресурсов OpenTelemetry только в том случае, если они предоставлены через переменные среды OTEL_SERVICE_NAME и OTEL_RESOURCE_ATTRIBUTES. При использовании API сбора трассировки OpenTelemetry это ограничение не применяется.
  • На основе атрибутов ресурсов OpenTelemetry невозможно создать атрибуты запроса (обычно используемые для поиска и фильтрации трассировок).
  • ЕдиныйАгент обрезает значения атрибутов, превышающие 4096 символов.

Предотвращение дублирования span в Java

ЕдиныйАгент версии 1.259+

Чтобы избежать возможных дубликатов диапазонов для областей, охватываемых OpenTelemetry и ЕдинымАгентом, ЕдиныйАгент пропускает диапазоны из следующих библиотек Java с автоматическим инструментированием, если ЕдиныйАгент настроен на инструментирование вашего приложения Java и прием диапазонов OpenTelemetry.

Такие интервалы пропускаются только ЕдиныйАгент. Экспорт в третьи стороны (например, в другие бэкенды или Collector) остаётся без изменений.

io.opentelemetry.akka-http-10.0 io.opentelemetry.apache-dbcp-2.0 io.opentelemetry.apache-httpasyncclient-4.1
io.opentelemetry.apache-httpclient-2.0 io.opentelemetry.apache-httpclient-4.0 io.opentelemetry.apache-httpclient-4.3
io.opentelemetry.apache-httpclient-5.0 io.opentelemetry.async-http-client-1.9 io.opentelemetry.async-http-client-2.0
io.opentelemetry.c3p0-0.9 io.opentelemetry.cassandra-3.0 io.opentelemetry.cassandra-4.0
io.opentelemetry.cassandra-4.4 io.opentelemetry.cxf-jaxrs-3.2 io.opentelemetry.google-http-client-1.19
io.opentelemetry.grpc-1.6 io.opentelemetry.http-url-connection io.opentelemetry.java-http-client
io.opentelemetry.jaxrs-1.0 io.opentelemetry.jaxrs-1.0-common io.opentelemetry.jaxrs-2.0-аннотации
io.opentelemetry.jaxrs-2.0-common io.opentelemetry.jaxrs-2.0-cxf-3.2 io.opentelemetry.jaxrs-2.0-jersey-2.0
io.opentelemetry.jaxrs-2.0-resteasy-3.0 io.opentelemetry.jaxrs-2.0-resteasy-3.1 io.opentelemetry.jaxrs-3.0-аннотации
io.opentelemetry.jaxrs-3.0-jersey-3.0 io.opentelemetry.jaxrs-3.0-resteasy-6.0 io.opentelemetry.jaxrs-annotations-2.0
io.opentelemetry.jaxrs-annotations-3.0 io.opentelemetry.jaxrs-client-1.1 io.opentelemetry.jaxrs-client-2.0
io.opentelemetry.jaxrs-client-2.0-resteasy-3.0 io.opentelemetry.jaxws-2.0 io.opentelemetry.jaxws-2.0-axis2-1.6
io.opentelemetry.jaxws-2.0-cxf-3.0 io.opentelemetry.jaxws-2.0-metro-2.2 io.opentelemetry.jaxws-cxf-3.0
io.opentelemetry.jaxws-common io.opentelemetry.jaxws-jws-api-1.1 io.opentelemetry.jdbc
io.opentelemetry.jedis-1.4 io.opentelemetry.jedis-3.0 io.opentelemetry.jedis-4.0
io.opentelemetry.jersey-2.0 io.opentelemetry.jetty-11.0 io.opentelemetry.jetty-8.0
io.opentelemetry.jetty-httpclient-9.2 io.opentelemetry.jms-1.1 io.opentelemetry.jms-3.0
io.opentelemetry.jsp-2.3 io.opentelemetry.kafka-clients io.opentelemetry.kafka-clients-0.11
io.opentelemetry.kafka-clients-2.6 io.opentelemetry.kafka-streams-0.11 io.opentelemetry.lettuce-5.1
io.opentelemetry.liberty io.opentelemetry.liberty-20.0 io.opentelemetry.mongo-3.1
io.opentelemetry.netty-3.8 io.opentelemetry.netty-4.0 io.opentelemetry.netty-4.1
io.opentelemetry.okhttp-2.2 io.opentelemetry.okhttp-3.0 io.opentelemetry.orcale-ucp-11.2 ( sic! )
io.opentelemetry.rabbitmq-2.7 io.opentelemetry.reactor-kafka-1.0 io.opentelemetry.reactor-netty-1.0
io.opentelemetry.resteasy-3.0 io.opentelemetry.resteasy-3.1 io.opentelemetry.resteasy-6.0
io.opentelemetry.rmi io.opentelemetry.servlet-2.2 io.opentelemetry.servlet-3.0
io.opentelemetry.servlet-5.0 io.opentelemetry.servlet-javax-common io.opentelemetry.spring-jms-2.0
io.opentelemetry.spring-jms-6.0 io.opentelemetry.spring-kafka-2.7 io.opentelemetry.spring-rabbit-1.0
io.opentelemetry.spring-rmi-4.0 io.opentelemetry.spring-webflux-5.0 io.opentelemetry.spring-webflux-5.3
io.opentelemetry.spring-ws-2.0 io.opentelemetry.tomcat-10.0 io.opentelemetry.tomcat-7.0
io.opentelemetry.tomcat-jdbc io.opentelemetry.undertow-1.4 io.opentelemetry.vibur-dbcp-11.0

Предотвращение дублирования span в PHP

ЕдиныйАгент версии 1.313+

Чтобы избежать возможных дубликатов диапазонов для областей, охватываемых OpenTelemetry и ЕдинымАгентом, ЕдиныйАгент пропускает диапазоны из следующих автоматических библиотек PHP-инструментации, если ЕдиныйАгент настроен на инструментирование вашего PHP-приложения и прием диапазонов OpenTelemetry.

Такие интервалы пропускаются только ЕдинымАгентом. Экспорт в третьи стороны (например, в другие бэкенды или Collector) остаётся без изменений.

io.opentelemetry.contrib.php.curl io.opentelemetry.contrib.php.laravel
io.opentelemetry.contrib.php.mongodb io.opentelemetry.contrib.php.mysqli
io.opentelemetry.contrib.php.pdo io.opentelemetry.contrib.php.slim
io.opentelemetry.contrib.php.symfony io.opentelemetry.contrib.php.wordpress
Источник — https://doc.fit4u.kz/index.php?title=Трассировки_OpenTelemetry_с_помощью_ЕдиногоАгента&oldid=5788