OpenTelemetry Span Metrics Gateway

Материал из Документация Ключ-АСТРОМ
Версия от 23:24, 22 октября 2026; Azubarev (обсуждение | вклад) ([wiki-cd:ruscomtech-extensions:b0985a6744c086353b26ac217dfa652296b8c814])
(разн.) ← Предыдущая версия | Текущая версия (разн.) | Следующая версия → (разн.)

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-спанов в метрики количества вызовов и продолжительности.
  • Поддержаны режимы «метрики и трассировки» и «только метрики».
  • Добавлены ограничения размера запросов, очереди обработки и количества временных рядов.
Источник — https://doc.ruscomtech.ru/index.php?title=OpenTelemetry_Span_Metrics_Gateway&oldid=7233