IKuznetsov: Новая страница: «Модули кода Ключ-АСТРОМ ЕдиныйАгент для '''Java, .NET, PHP, Python, Node.js''' и '''Go''' автоматически собир...»

2025-09-26T17:55:52Z

Новая страница: «Модули кода Ключ-АСТРОМ ЕдиныйАгент для '''Java, .NET, PHP, Python, Node.js''' и '''Go''' автоматически собир...»

Новая страница

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

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

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

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

== Требования ==

=== Java ===
{| class="wikitable"
!Структура мониторинга
!Версии
|-
|[https://github.com/open-telemetry/opentelemetry-java/ OpenTelemetry]
|1,0 - 1,31 ,1,4 - 1,541
|-
|[https://opentracing.io/guides/java/ OpenTracing]
|0,33,0,32,0,31
|}
1 Поддерживается в '''AWS Lambda'''.

=== Go ===
{| class="wikitable"
!Структура мониторинга
!Версии
|-
|[https://github.com/open-telemetry/opentelemetry-go/ OpenTelemetry]
|1,0 - 1,7,1.8 - 1.11.0,1.11.1 - 1.27,1.28 - 1.38
|}

=== Node.js ===
{| class="wikitable"
!Структура мониторинга
!Версии
|-
|[https://www.npmjs.com/package/@opentelemetry/api OpenTelemetry]
|11
|}
1 Поддерживается в AWS Lambda.

=== PHP ===
{| class="wikitable"
!Структура мониторинга
!Версии
|-
|[https://github.com/open-telemetry/opentelemetry-php OpenTelemetry]
|1.0.0
|}

=== .NET and .NET Core ===
{| class="wikitable"
!Структура мониторинга
!Версии
|-
|[https://github.com/open-telemetry/opentelemetry-dotnet OpenTelemetry]
|1.0.1+,1.1+
|}

=== .NET Framework ===
{| class="wikitable"
!Структура мониторинга
!Версии
|-
|[https://github.com/open-telemetry/opentelemetry-dotnet OpenTelemetry]
|1.0.1+,1.1+
|}

=== Python ===
{| class="wikitable"
!Структура мониторинга
!Версии
|-
|[https://github.com/open-telemetry/opentelemetry-python OpenTelemetry]
|1.1+
|}

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

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

* Go
* .NET
* Node.js
* PHP
* Python

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Точки входа ===
Ещё одно отличие заключается в обработке интервалов точек входа (первый интервал трассировки). Во избежание возможных конфликтов с существующими трассировками '''PurePath''', ЕдиныйАгент по умолчанию принимает только интервалы с [https://opentelemetry.io/docs/concepts/signals/traces/#span-kind типом интервала] <code>Server</code> или <code>Consumer</code>. Обычно это не является проблемой, поскольку библиотеки инструментирования обычно настраивают соответствующий тип интервала, однако это следует учитывать, если ваше приложение полностью использует ручное инструментирование.

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

[[Файл:Image4054.png|граница]]

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

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

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

[[Файл:Image4055.png|граница]]

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

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

[[Файл:Image4057.png|граница]]
{| class="wikitable"
|Постарайтесь избегать объединения трассировок для технологий, уже изначально охватываемых датчиками ЕдиногоАгента. Объединение таких областей '''OpenTelemetry''' в трассировку ЕдиногоАгента может привести к неопределённым состояниям.
|}

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

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

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

Чтобы обеспечить корреляцию между этими двумя идентификаторами, Ключ-АСТРОМ создает дополнительные [https://opentelemetry.io/docs/specs/otel/overview/#links-between-spans ссылки для каждого диапазона], ссылаясь на трассировку '''OpenTelemetry'''.

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

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

=== Java ===

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

=== Go ===

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

=== Node.js ===

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

=== PHP ===

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

=== Python ===

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

=== Все языки ===

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

== Предотвращение дублирования span в Java ==
<code>ЕдиныйАгент версии 1.259+</code>

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

Такие интервалы пропускаются только ЕдиныйАгент. Экспорт в третьи стороны (например, в другие бэкенды или Collector) остаётся без изменений.
{| class="wikitable"
|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 ==
<code>ЕдиныйАгент версии 1.313+</code>

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

Такие интервалы пропускаются только ЕдинымАгентом. Экспорт в третьи стороны (например, в другие бэкенды или Collector) остаётся без изменений.
{| class="wikitable"
|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
|}

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

IKuznetsov: Новая страница: «Модули кода Ключ-АСТРОМ ЕдиныйАгент для '''Java, .NET, PHP, Python, Node.js''' и '''Go''' автоматически собир...»