OpenTelemetry Span Metrics Gateway

OpenTelemetry Span Metrics Gateway

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

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

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

Возможности

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

Схема работы

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

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

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

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

Требования

• Ключ-АСТРОМ 1.300+.
• АктивныйШлюз с включённым EEC и средой Python не ниже 3.10 в составе EEC. Локальное выполнение на ЕдиномАгенте не поддерживается; зависимости поставляются в пакете расширения.
• На выбранном сервере EEC должен быть свободен TCP-порт для приёма OTLP-запросов.
• Приложения или OpenTelemetry Collector должны иметь сетевой доступ к серверу EEC.
• Экспорт трассировок должен использовать протокол http/protobuf.
• Для пересылки трассировок в кластер необходим токен с разрешением openTelemetryTrace.ingest.
• Межсетевой экран должен разрешать подключения к настроенному порту шлюза.

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

Входящий приёмник использует HTTP, а Bearer-токен сам по себе не шифрует соединение. Ограничьте доступ к порту доверенными отправителями; если требуется шифрование на входе, используйте защищённый канал или TLS на обратном прокси. Параметр проверки TLS в расширении относится к исходящей пересылке, а не к приёмнику.

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

1. Скачайте пакет расширения.
2. В интерфейсе Ключ-АСТРОМ откройте раздел управления расширениями.
3. Загрузите архив расширения.
4. Откройте расширение ru.ruscomtech.otel-span-metrics-gateway.
5. Добавьте конфигурацию мониторинга.
6. Выберите группу АктивныхШлюзов с EEC, на которой должен работать OTLP-шлюз.
7. Добавьте конечную точку шлюза и заполните параметры.
8. Сохраните и активируйте конфигурацию.

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

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

• Адрес прослушивания (listen_address) — IP-адрес интерфейса узла выполнения. По умолчанию 0.0.0.0, то есть все интерфейсы.
• Порт прослушивания (listen_port) — TCP-порт OTLP/HTTP, по умолчанию 4318.
• Пересылать трейсы в кластер (forward_traces) — по умолчанию включено. При выключении создаются только метрики.
• URL для OTLP-трейсов кластера (forward_url) — полный адрес OTLP API с путём /v1/traces; обязателен при включённой пересылке.
• API-токен кластера (forward_api_token) — секретное поле для токена с разрешением openTelemetryTrace.ingest, если целевой endpoint требует аутентификации.
• Проверять TLS-сертификат кластера (verify_forward_tls) — по умолчанию включено. Не отключайте проверку в рабочей среде.
• Bearer-токен приёмника (receiver_bearer_token) — необязательный секрет для входящих запросов. Отправители должны передавать Authorization: Bearer <token>.
• Атрибуты спана для dimensions (dimension_attributes) — список ключей через запятую, по умолчанию peer.service,net.peer.ip.
• Числовые атрибуты спана (numeric_attributes) — до 20 ключей через запятую для агрегации числовых значений. По умолчанию поле пустое и сбор отключён.
• Максимальное количество временных рядов (max_series) — предел уникальных комбинаций измерений за интервал отправки, по умолчанию 2000, диапазон 100–20000.
• Максимальный размер распакованного OTLP-запроса (max_request_mib) — по умолчанию 8 MiB, диапазон 1–64 MiB.
• Рабочие потоки приёмника (worker_threads) — число параллельно обрабатываемых запросов, по умолчанию 4.
• Размер очереди запросов (request_queue_size) — число запросов в ожидании свободного потока, по умолчанию 16.
• Интервал отправки метрик (flush_interval_seconds) — по умолчанию 15 секунд, диапазон 5–300.
• Тайм-аут пересылки трейсов (forward_timeout_seconds) — ожидание ответа OTLP API, по умолчанию 10 секунд; используется только при включённой пересылке.

Пример URL для пересылки трассировок через АктивныйШлюз окружения:

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

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

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

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

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

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

OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <token>"

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

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

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

Пример файла config.yaml:

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/v1/traces
    encoding: proto
    compression: gzip
    headers:
      Authorization: "Bearer <receiver-token>"
    timeout: 10s

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

Замените:

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

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

headers:
  Authorization: "Bearer <receiver-token>"

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

exporters:
  otlphttp/span_metrics_gateway:
    traces_endpoint: http://eec.example.local:4318/v1/traces

В traces_endpoint указывается полный путь /v1/traces; в отличие от общего endpoint, этот параметр не добавляет путь автоматически. См. документацию OTLP HTTP exporter.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример:

peer.service,net.peer.ip,http.request.method

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

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

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

otel.metric.overflow=true

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

Сбор числовых атрибутов

В поле Числовые атрибуты спана (numeric_attributes) перечислите до 20 точных ключей, например:

order.amount,items.count

Для каждого ключа расширение отправляет otel.span.attribute.value с измерением attribute.key и агрегатами минимума, максимума, суммы и количества значений за интервал. Значения сохраняют исходный масштаб: автоматического пересчёта единиц измерения нет.

• Поддерживаются числа и строки, которые можно преобразовать в конечное число. Логические значения не считаются числами.
• Подстановка * в этом поле не поддерживается: ключи задаются явно.
• Выбранные числовые ключи исключаются из обычных измерений, в том числе при dimension_attributes=*. Это предотвращает создание отдельного ряда для каждого числового значения.
• Resource attributes автоматически не читаются. При необходимости предварительно скопируйте их в атрибуты спана на стороне Collector.
• Некорректные значения, NaN, бесконечность и значения, вызывающие переполнение суммы, пропускаются и учитываются в otel.span.gateway.invalid_attribute_values по attribute.key.

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

• otel.span.calls — количество успешно обработанных спанов с разделением по имени спана и настроенным атрибутам.
• otel.span.duration — продолжительность спанов в миллисекундах.
• otel.span.attribute.value — минимум, максимум, сумма и количество выбранных числовых атрибутов; ключ атрибута указан в attribute.key.
• otel.span.gateway.invalid_attribute_values — количество пропущенных некорректных числовых значений по attribute.key.
• otel.span.gateway.requests — количество успешно обработанных OTLP-запросов.
• otel.span.gateway.spans — количество спанов в обработанных запросах.
• otel.span.gateway.rejected_requests — количество отклонённых запросов с причиной в reason.
• otel.span.gateway.forward_errors — количество ошибок пересылки трассировок.
• otel.span.gateway.active_series — количество активных временных рядов за интервал агрегации.
• otel.span.gateway.overflow_spans — количество спанов в overflow-ряде из-за ограничения кардинальности.

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

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

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

curl http://eec.example.local:4318/healthz

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

ok

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

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

Если настроен numeric_attributes, дополнительно проверьте otel.span.attribute.value по нужному attribute.key и отсутствие роста otel.span.gateway.invalid_attribute_values.

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

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

Версия 0.1.20

• Добавлен параметр numeric_attributes для сбора до 20 выбранных числовых атрибутов спана.
• Добавлена метрика otel.span.attribute.value с агрегатами минимума, максимума, суммы и количества значений и измерением attribute.key.
• Числовые атрибуты исключены из измерений, включая режим *.
• Добавлена метрика otel.span.gateway.invalid_attribute_values для пропущенных некорректных значений и переполнения суммы.

Версия 0.1.19

• Используется идентификатор ru.ruscomtech.otel-span-metrics-gateway.
• Добавлен шлюз для преобразования OTLP-спанов в метрики количества вызовов и продолжительности.
• Поддержаны режимы «метрики и трассировки» и «только метрики».
• Добавлены ограничения размера запросов, очереди обработки и количества временных рядов.