OpenTelemetry Span Metrics Gateway

OpenTelemetry Span Metrics Gateway

Расширение принимает трассировки по протоколу 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 не поддерживаются.

Требования

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

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

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

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

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

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

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

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

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

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

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

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

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
    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

После изменения конфигурации перезапустите 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.

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

Метрика	Описание
otel.span.calls	Количество успешно обработанных спанов. Метрика разделяется по имени спана и настроенным атрибутам.
otel.span.duration	Продолжительность обработанных спанов в миллисекундах.
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.

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

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

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