Трассировка (tracing)

Функция tracing включает распределенную трассировку Netgap. Она помогает увидеть путь одного запроса через netgap_gateway, внутренний request bridge, netgap_executor и целевой сервис.

Назначение

Трассировка нужна, чтобы:

• связать операции gateway и executor в один trace_id;
• увидеть задержки на отдельных этапах обработки запроса;
• проверить, где именно возникла ошибка или деградация;
• передавать контекст трассировки дальше в upstream и downstream компоненты.

Netgap использует OpenTelemetry и W3C Trace Context. При прохождении через внутренние транспорты контекст передается явно, поэтому спаны gateway и executor остаются частью одной трассы.

Настройки

Секция observability.tracing включает экспорт спанов.

Поле	Значения	Описание
destination	Jaeger	Тип назначения. Используется OTLP/gRPC endpoint, совместимый с Jaeger или OpenTelemetry Collector.
destination_args	URL	Адрес приемника спанов, например http://otel-collector.example.local:4317.
service_name	Строка	Имя сервиса в OpenTelemetry resource. По нему сервис отображается в Jaeger и других backends.

Отдельного поля level в секции observability.tracing нет. При инициализации трассировки Netgap создает OpenTelemetry layer и применяет внутренний фильтр off,netgap_gateway=debug,netgap_executor=debug: по умолчанию в tracing backend попадают отладочные и более важные спаны компонентов netgap_gateway и netgap_executor, а события остальных target-ов не экспортируются. Это снижает шум в трассировке и не смешивает ее с audit-событиями и сторонней технической диагностикой.

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

Экспорт трассировки в OpenTelemetry Collector или Jaeger-compatible endpoint:

observability:
  service_name: netgap-gateway
  event_targets:
    - level: info
      target_id: Tech
      target_destination: Console
      target_args: ""
      format: ColorizedANSI
  tracing:
    destination: Jaeger
    destination_args: http://otel-collector.example.local:4317
    service_name: netgap-gateway

Разные имена сервисов для gateway и executor:

# gateway
observability:
  service_name: netgap-gateway
  event_targets:
    - level: info
      target_id: Tech
      target_destination: Console
      target_args: ""
      format: ColorizedANSI
  tracing:
    destination: Jaeger
    destination_args: http://otel-collector.example.local:4317
    service_name: netgap-gateway

---

# executor
observability:
  service_name: netgap-executor
  event_targets:
    - level: info
      target_id: Tech
      target_destination: Console
      target_args: ""
      format: ColorizedANSI
  tracing:
    destination: Jaeger
    destination_args: http://otel-collector.example.local:4317
    service_name: netgap-executor

Результат и доставка

Результат работы функции — OpenTelemetry spans. Они отправляются по OTLP/gRPC на endpoint из destination_args. В качестве приемника можно использовать Jaeger с OTLP endpoint или OpenTelemetry Collector, который дальше передаст трассы в Jaeger, Tempo или другой tracing backend.

В интерфейсе tracing backend пользователь видит цепочку обработки запроса, например:

netgap_gateway
  handle incoming request
    queuing
      pulling
        netgap_executor
          handle request in private zone
            call target

Варианты применения

• расследование медленных запросов и ошибок на границе gateway/executor;
• проверка корректности propagation заголовков traceparent и tracestate;
• анализ задержек между приемом запроса, постановкой в очередь, обработкой executor и вызовом целевого сервиса;
• интеграция Netgap в общую tracing-инфраструктуру организации.