Просмотр кода страницы OpenTelemetry Span Metrics Gateway

= OpenTelemetry Span Metrics Gateway =

Расширение принимает трассировки по протоколу OTLP/HTTP, формирует из спанов метрики количества вызовов и продолжительности и при необходимости пересылает исходные трассировки в кластер Ключ-АСТРОМ.

Расширение выполняется удалённо на сервере EEC.

'''Идентификатор расширения:''' <code>ru.ruscomtech.otel-span-metrics-gateway</code>

== Возможности ==

* приём трассировок через OTLP/HTTP;
* поддержка бинарного формата protobuf;
* поддержка сжатия gzip;
* создание метрик количества и продолжительности спанов;
* добавление атрибутов спанов в измерения метрик;
* ограничение количества временных рядов;
* защита входящего endpoint с помощью Bearer-токена;
* пересылка исходных трассировок в кластер Ключ-АСТРОМ;
* контроль отклонённых запросов и ошибок пересылки.

== Схема работы ==

<pre>
Приложение или OpenTelemetry Collector
        |
        | OTLP/HTTP protobuf
        v
OpenTelemetry Span Metrics Gateway на EEC
        |
        +-- метрики спанов --> Ключ-АСТРОМ
        |
        +-- исходные трассировки --> OTLP API Ключ-АСТРОМ
</pre>

Шлюз принимает трассировки по следующим путям:

* <code>/v1/traces</code> — стандартный путь OTLP/HTTP;
* <code>/otlp/v1/traces</code> — дополнительный поддерживаемый путь.

OTLP/gRPC и OTLP/JSON не поддерживаются.

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

* На выбранном сервере EEC должен быть свободен TCP-порт для приёма OTLP-запросов.
* Приложения или OpenTelemetry Collector должны иметь сетевой доступ к серверу EEC.
* Экспорт трассировок должен использовать протокол <code>http/protobuf</code>.
* Для пересылки трассировок в кластер необходим токен с разрешением <code>openTelemetryTrace.ingest</code>.
* Межсетевой экран должен разрешать подключения к настроенному порту шлюза.

Стандартный порт OTLP/HTTP — <code>4318</code>. Если он уже используется другим сервисом, укажите свободный порт.

== Установка расширения ==

# Скачайте пакет расширения.
# В интерфейсе Ключ-АСТРОМ откройте раздел управления расширениями.
# Загрузите архив расширения.
# Откройте расширение <code>ru.ruscomtech.otel-span-metrics-gateway</code>.
# Добавьте конфигурацию мониторинга.
# Выберите группу EEC, на которой должен работать OTLP-шлюз.
# Добавьте конечную точку шлюза и заполните параметры.
# Сохраните и активируйте конфигурацию.

Для одной конфигурации можно создать только одну конечную точку шлюза.

== Настройка шлюза ==

{| class="wikitable"
! Параметр
! Значение по умолчанию
! Описание
|-
| Адрес прослушивания
| <code>0.0.0.0</code>
| IP-адрес интерфейса EEC. Значение <code>0.0.0.0</code> разрешает подключения на всех интерфейсах.
|-
| Порт прослушивания
| <code>4318</code>
| TCP-порт для входящих запросов OTLP/HTTP.
|-
| Пересылать трейсы в кластер
| Включено
| При включении шлюз создаёт метрики и пересылает исходные трассировки. При выключении создаются только метрики.
|-
| URL для OTLP-трейсов кластера
| —
| Полный адрес OTLP API, заканчивающийся на <code>/v1/traces</code>.
|-
| API-токен кластера
| —
| Токен с разрешением <code>openTelemetryTrace.ingest</code>.
|-
| Проверять TLS-сертификат
| Включено
| Проверка сертификата при пересылке трассировок. Отключать рекомендуется только при тестировании.
|-
| Bearer-токен приёмника
| —
| Необязательный токен для защиты входящего OTLP endpoint.
|-
| Атрибуты спана для dimensions
| <code>peer.service,net.peer.ip</code>
| Атрибуты спана, которые необходимо добавить в измерения метрик.
|-
| Максимальное количество временных рядов
| <code>2000</code>
| Ограничение количества уникальных комбинаций измерений за один интервал отправки.
|-
| Максимальный размер запроса
| <code>8 MiB</code>
| Максимальный размер OTLP-запроса после распаковки.
|-
| Рабочие потоки
| <code>4</code>
| Количество запросов, которые могут обрабатываться параллельно.
|-
| Размер очереди запросов
| <code>16</code>
| Количество запросов, ожидающих свободный рабочий поток.
|-
| Интервал отправки метрик
| <code>15 секунд</code>
| Период агрегации и отправки метрик в Ключ-АСТРОМ.
|-
| Тайм-аут пересылки трассировок
| <code>10 секунд</code>
| Максимальное время ожидания ответа от OTLP API.
|}

Пример URL для пересылки трассировок через Environment ActiveGate:

<pre>
https://activegate.example.local:9999/e/ENVIRONMENT_ID/api/v2/otlp/v1/traces
</pre>

Если пересылка трассировок отключена, URL и API-токен заполнять не требуется.

== Настройка отправителя OTLP ==

Пример переменных окружения приложения или OpenTelemetry Collector:

<pre>
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://eec.example.local:4318/v1/traces
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
</pre>

Если в конфигурации шлюза задан Bearer-токен:

<pre>
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <token>"
</pre>

Значение токена на стороне отправителя должно совпадать со значением поля «Bearer-токен приёмника».

=== Пример конфигурации OpenTelemetry Collector ===

OpenTelemetry Collector может принимать трассировки от приложений и передавать их в шлюз, работающий на сервере EEC.

Пример файла <code>config.yaml</code>:

<pre>
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  otlp_http/span_metrics_gateway:
    traces_endpoint: http://eec.example.local:4318
    encoding: proto
    compression: gzip
    headers:
      Authorization: "Bearer &lt;receiver-token&gt;"
    timeout: 10s

service:
  pipelines:
    traces:
      receivers:
        - otlp
      processors:
        - batch
      exporters:
        - otlp_http/span_metrics_gateway
</pre>

Замените:

* <code>eec.example.local</code> — адресом сервера EEC, на котором работает расширение;
* <code>4318</code> — портом, указанным в конфигурации шлюза;
* <code>&lt;receiver-token&gt;</code> — значением поля «Bearer-токен приёмника».

Если Bearer-токен в расширении не настроен, удалите из конфигурации блок:

<pre>
headers:
  Authorization: "Bearer &lt;receiver-token&gt;"
</pre>

В старых версиях OpenTelemetry Collector компонент экспортёра может называться <code>otlphttp</code>:

<pre>
exporters:
  otlphttp/span_metrics_gateway:
    traces_endpoint: http://eec.example.local:4318
</pre>

После изменения конфигурации перезапустите OpenTelemetry Collector и проверьте появление метрики <code>otel.span.gateway.requests</code>.

'''Важно:''' расширение добавляет в измерения только атрибуты спанов. Resource attributes, например <code>service.name</code>, автоматически не используются.

Если необходимо группировать метрики по имени сервиса, в OpenTelemetry Collector Contrib можно скопировать <code>service.name</code> из resource attributes в атрибут спана:

<pre>
processors:
  transform/span_dimensions:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - set(attributes["service.name"], resource.attributes["service.name"])
            where resource.attributes["service.name"] != nil
</pre>

Затем добавьте процессор в трассировочный pipeline:

<pre>
service:
  pipelines:
    traces:
      receivers:
        - otlp
      processors:
        - transform/span_dimensions
        - batch
      exporters:
        - otlp_http/span_metrics_gateway
</pre>

В конфигурации расширения добавьте <code>service.name</code> в поле «Атрибуты спана для dimensions».

== Режимы работы ==

=== Метрики и трассировки ===

При включённой пересылке шлюз:

# принимает OTLP-запрос;
# декодирует спаны;
# пересылает исходный запрос в OTLP API;
# после успешной пересылки учитывает спаны в метриках.

Если кластер возвращает ошибку или недоступен, увеличивается метрика <code>otel.span.gateway.forward_errors</code>.

=== Только метрики ===

При выключенной пересылке шлюз создаёт метрики из принятых спанов, но не отправляет исходные трассировки в кластер.

== Настройка измерений ==

Измерение <code>span.name</code> добавляется автоматически.

В поле «Атрибуты спана для dimensions» можно:

* перечислить необходимые атрибуты через запятую;
* указать <code>*</code> для автоматического добавления допустимых атрибутов спана;
* оставить поле пустым, если дополнительные измерения не нужны.

Пример:

<pre>
peer.service,net.peer.ip,http.request.method
</pre>

Resource attributes в измерения метрик не добавляются.

Использование <code>*</code> может значительно увеличить кардинальность метрик. Для рабочих сред рекомендуется перечислять только необходимые атрибуты.

Если количество уникальных комбинаций измерений превышает установленный предел, оставшиеся спаны объединяются в ряд:

<pre>
otel.metric.overflow=true
</pre>

Количество таких спанов отображается в метрике <code>otel.span.gateway.overflow_spans</code>.

== Собираемые метрики ==

{| class="wikitable"
! Метрика
! Описание
|-
| <code>otel.span.calls</code>
| Количество успешно обработанных спанов. Метрика разделяется по имени спана и настроенным атрибутам.
|-
| <code>otel.span.duration</code>
| Продолжительность обработанных спанов в миллисекундах.
|-
| <code>otel.span.gateway.requests</code>
| Количество успешно обработанных OTLP-запросов.
|-
| <code>otel.span.gateway.spans</code>
| Общее количество спанов в обработанных запросах.
|-
| <code>otel.span.gateway.rejected_requests</code>
| Количество отклонённых запросов с измерением <code>reason</code>.
|-
| <code>otel.span.gateway.forward_errors</code>
| Количество ошибок пересылки трассировок в кластер.
|-
| <code>otel.span.gateway.active_series</code>
| Количество активных временных рядов в текущем интервале агрегации.
|-
| <code>otel.span.gateway.overflow_spans</code>
| Количество спанов, объединённых в overflow-ряд из-за ограничения кардинальности.
|}

Все метрики входят в набор функций <code>default</code>.

== Проверка работы ==

Проверьте состояние HTTP-приёмника:

<pre>
curl http://eec.example.local:4318/healthz
</pre>

Исправный шлюз возвращает:

<pre>
ok
</pre>

После отправки трассировок проверьте:

* состояние конфигурации расширения;
* появление метрики <code>otel.span.gateway.requests</code>;
* появление метрик <code>otel.span.calls</code> и <code>otel.span.duration</code>;
* отсутствие постоянного роста <code>otel.span.gateway.rejected_requests</code>;
* отсутствие ошибок <code>otel.span.gateway.forward_errors</code>;
* значение <code>otel.span.gateway.overflow_spans</code>.

Код ответа <code>401</code> указывает на ошибку Bearer-токена, <code>413</code> — на превышение размера запроса, <code>415</code> — на неподдерживаемый формат, а <code>503</code> — на переполнение очереди шлюза.

== История изменений ==

{| class="wikitable"
! Версия
! Изменения
|-
| 0.1.19
|
* Используется идентификатор <code>ru.ruscomtech.otel-span-metrics-gateway</code>.
* Добавлен шлюз для преобразования OTLP-спанов в метрики количества вызовов и продолжительности.
* Поддержаны режимы «метрики и трассировки» и «только метрики».
* Добавлены ограничения размера запросов, очереди обработки и количества временных рядов.
|}