Просмотр кода страницы Конечные точки API Ключ-АСТРОМ OTLP

Протокол [https://opentelemetry.io/docs/specs/otlp/ OpenTelemetry (OTLP)] — это основной сетевой протокол для обмена телеметрическими данными между сервисами и приложениями, использующими протокол '''OpenTelemetry'''.

Ключ-АСТРОМ предоставляет собственные '''OTLP'''-интерфейсы со следующими сервисами:

* Платформа Ключ-АСТРОМ Managed
* Экземпляры АктивногоШлюза

{| class="wikitable"
|В качестве альтернативы, вы можете развернуть [[Collector Ключ-АСТРОМ|Ключ-АСТРОМ Collector]] в качестве промежуточного сервисного приложения для пакетной обработки запросов и повышения производительности сети, или для преобразования запросов перед их пересылкой в Ключ-АСТРОМ (например, для маскировки конфиденциальных данных).
|}

== Пути загрузки по умолчанию ==
Пути приема данных, используемые Ключ-АСТРОМ для отдельных типов сигналов, соответствуют [https://opentelemetry.io/docs/specs/otel/protocol/exporter/#endpoint-urls-for-otlphttp стандартным путям '''OpenTelemetry'''].
{| class="wikitable"
!Тип сигнала
!Путь
|-
|Трассировки
|<code>/v1/traces</code>
|-
|Метрики
|<code>/v1/metrics</code>
|-
|Логи
|<code>/v1/logs</code>
|}
В зависимости от конфигурации, при указании URL-адресов экспорта может потребоваться добавить эти пути по отдельности к базовым URL-адресам следующих конечных точек сервиса. Это можно сделать либо в коде, либо при использовании ручной инструментации, либо с помощью стандартных [https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#endpoint-configuration переменных среды].

== Экспорт в Ключ-АСТРОМ ==

=== Базовые URL-адреса ===
Приведенные ниже адреса представляют собой базовые URL-адреса для конфигурации приема OTLP-трафика. Используйте URL-адрес, соответствующий вашему типу среды, и замените соответствующую часть идентификатором вашей среды .
{| class="wikitable"
!Тип API
!Базовый URL
|-
|Ключ-АСТРОМ Managed
|<code><nowiki>https://{your-domain}/e/{your-environment-id}/api/v2/otlp</nowiki></code>
|-
|Окружение АктивногоШлюза <sup>1</sup>
|<code><nowiki>https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp</nowiki></code>
|-
|Контейнерная среда АктивногоШлюза <sup>2</sup>
|<code><nowiki>https://{your-activegate-domain}/e/{your-environment-id}/api/v2/otlp</nowiki></code>
|}
<sup>1</sup> В настройках среды АктивныхШлюзов по умолчанию используется порт <code>9999</code>. Если вы изменили этот порт, скорректируйте его в URL-адресе соответствующим образом.

<sup>2</sup> Для этой конструкции необходима  [[Настройка постоянного хранилища для АктивногоШлюза|PVC]].

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

==== Кластер АктивногоШлюза ====
{| class="wikitable"
!Тип сигнала
!URL
|-
|Трассировки
|<code><nowiki>https://{your-domain}/e/{your-environment-id}/api/v2/otlp/v1/traces</nowiki></code>
|-
|Метрики
|<code><nowiki>https://{your-domain}/e/{your-environment-id}/api/v2/otlp/v1/metrics</nowiki></code>
|-
|Логи
|<code><nowiki>https://{your-domain}/e/{your-environment-id}/api/v2/otlp/v1/logs</nowiki></code>
|}

==== Среда АктивногоШлюза ====
{| class="wikitable"
!Тип сигнала
!URL
|-
|Трассировки
|<code><nowiki>https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp/v1/traces</nowiki></code>
|-
|Метрики
|<code><nowiki>https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp/v1/metrics</nowiki></code>
|-
|Логи
|<code><nowiki>https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/otlp/v1/logs</nowiki></code>
|}

=== Ограничения API ===
При обращении к конечным точкам API Ключ-АСТРОМ действуют следующие ограничения.

* Поддержка '''gRPC''' отсутствует. Для вызовов '''API''' необходимо использовать протокол '''HTTP'''.
* '''JSON''' не поддерживается для протоколов '''Protocol Buffers'''. Необходимо использовать двоичный формат.

=== Аутентификация ===
Аутентификация осуществляется с помощью токена доступа к '''API''' и заголовка <code>Authorization</code> HTTP.

<u>Это необходимо только для экспорта в АктивномШлюзе.</u>
{| class="wikitable"
|Authorization: Api-Token dt.....
|}
Чтобы получить токен доступа в Ключ-АСТРОМ, перейдите в раздел '''Токены доступа'''. Используйте следующие области доступа для экспортируемых сигналов.
{| class="wikitable"
!Тип сигнала
!Область доступа
|-
|Трассировки
|<code>openTelemetryTrace.ingest</code>
|-
|Метрики
|<code>metrics.ingest</code>
|-
|Логи
|<code>logs.ingest</code>
|}
Конечно, вы также можете комбинировать области действия. Для получения дополнительной информации о токенах доступа см. [[Токены и аутентификация (API)|Ключ-АСТРОМ API — Токены и аутентификация]].

=== Требования к сети ===
Убедитесь, что верны следующие утверждения:

* <u>TCP-порт не заблокирован</u>

Поскольку обмен данными по протоколу '''OTLP''' с АктивнымШлюзов осуществляется через порты '''443''' (для '''SaaS''' и '''Managed''' решений) или '''9999''' (для АктивногоШлюза, работающих в среде), убедитесь, что соответствующий '''TCP'''-порт не блокируется брандмауэром или любым другим используемым вами решением для управления сетью.

* <u>Хранилище доверенных сертификатов вашей системы обновлено</u>

Во избежание возможных проблем с '''SSL'''-сертификатами, связанных с просроченными или отсутствующими корневыми сертификатами по умолчанию, убедитесь, что хранилище доверенных сертификатов вашей системы обновлено.

== Экспорт коллекционеру ==
Использование '''Collector''' в качестве промежуточного шлюза позволяет централизованно оптимизировать и упорядочивать телеметрические данные и запросы. См. [[Варианты использования Collector|примеры использования Collector]] для получения дополнительной информации и примеров конфигураций для популярных сценариев использования Collector.

Дополнительные сведения о настройке экземпляра Collector см. в документации [[Collector Ключ-АСТРОМ|Ключ-АСТРОМ Collector]].
{| class="wikitable"
|<u>Преобразование gRPC</u>
Поскольку в настоящее время Ключ-АСТРОМ требует экспорта '''OTLP''' с использованием '''HTTP''', вы можете использовать '''Collector''' для преобразования экспорта '''gRPC''' в '''HTTP'''.

Дополнительные сведения см. в разделе [[Преобразование OTLP gRPC]].
|}

=== Аутентификация и TLS ===
Необходимость использования '''TLS''' и аутентификации запросов к '''Collector''' зависит от конкретной конфигурации вашего '''Collector'''. По умолчанию [https://github.com/open-telemetry/opentelemetry-collector/blob/v0.140.0/receiver/otlpreceiver/README.md приемник '''OTLP'''] настроен для '''HTTP'''-запросов в открытом текстовом формате и не требует аутентификации.
{| class="wikitable"
|Для установления конечного исходящего соединения между '''Collector''' и Ключ-АСТРОМ всегда требуется аутентификация и протокол '''TLS'''.
|}

=== Требования к сети ===
Убедитесь, что верны следующие утверждения:

* <u>Сетевые порты не заблокированы</u>

Убедитесь, что сетевые порты, необходимые для настроенных экземпляров приемника, не заблокированы брандмауэром или любым другим решением для управления сетью, используемым в вашей инфраструктуре.