Подключение OpenTelemetry

На этой странице:

• Введение
• Агент или коллектор
• Включение поддержки OpenTelemetry на агенте
• Отправка трейсов и метрик OpenTelemetry Агенту ProtoOBP
• Отправка через существующий OpenTelemetry Collector
• Логи OpenTelemetry-приложений
• Примеры подключения OpenTelemetry инструментации
  • Keycloak
  • Ingress NGINX Controller
    • Если вы НЕ используете Ingress-NGINX Helm chart
    • Если вы используете Ingress-NGINX Helm chart
  • Инструментация Go через eBPF (AutoSDK)

Введение

OpenTelemetry – это open source observability framework, предоставляющий ИТ-командам стандартизированные протоколы и инструменты для сбора и маршрутизации телеметрии приложений (метрики, логи и трейсы). Созданный в качестве инкубаторского проекта Cloud Native Computing Foundation (CNCF), OpenTelemetry обеспечивает единообразный формат данных для их инструментации, генерации, сбора и экспорта в платформы мониторинга.

Proto Observability Platform нативно поддерживает формат данных OpenTelemetry.

Если ваши приложения и сервисы инструментированы библиотеками OpenTelemetry, вы можете выбрать способ отправки трейсов, метрик и логов в бэкэнд Proto Observability Platform.

Агент или коллектор

Трейсы OpenTelemetry можно принимать двумя способами — выбор зависит от того, что у вас уже развёрнуто:

• Если у вас уже настроена инфраструктура OpenTelemetry (собственный OpenTelemetry Collector, приложения уже отправляют OTLP) — используйте proto-otel-collector. Менять приложения не нужно: направьте телеметрию из вашего коллектора в коллектор ProtoOBP. Подробнее — OpenTelemetry в Proto Observability Platform.

• Если у вас уже развёрнуты Агенты ProtoOBP и инструментация на трейсерах ProtoOBP или Datadog, а нужно добавить новый источник, который работает только с OpenTelemetry, — отправляйте трейсы в Агент (встроенный OTLP-приём, разделы ниже).

Включение поддержки OpenTelemetry на агенте

Proto Observability Platform поддерживает стандарт W3C Trace Context, обеспечивая захват полного трейса, даже если запрос перемещается между сервисами, которые были инструментированы различными средствами. Обработка данных OTLP в Агентe ProtoOBP позволяет отправлять данные телеметрии непосредственно из приложений, оснащенных SDK OpenTelemetry. Агент может получать трейсы OTLP и метрики OTLP через gRPC или HTTP.

Чтобы приступить к работе, сначала подключите инструментацию для своего приложения с помощью OpenTelemetry SDK. Затем экспортируйте данные телеметрии в формате OTLP в Агента. Настройка этого зависит от типа инфраструктуры, на которой развернут ваш сервис, как описано на странице ниже. Хотя целью является совместимость с последней версией OTLP, обработка OTLP в Агенте совместима не со всеми версиями OTLP.

Ознакомьтесь с документацией по инструментации OpenTelemetry, чтобы понять, как направить данные в Агента. Раздел receiver, описанный ниже, соответствует схеме конфигурации receiver в OTLP OpenTelemetry Collector.

По умолчанию OTLP интеграция отключена, вы можете включить ее, изменив конфигурацию файла protoobp.yaml Агента или задав переменные окружения. Следующие конфигурации protoobp.yaml включают эндпоинты на портах по умолчанию. Для удобства в следующих примерах в качестве адреса эндпоинта используется 0.0.0.0. Это позволяет подключаться с любого сетевого интерфейса.

• Хост
• Docker
• Kubernetes

otlp_config:
  receiver:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

otlp_config:
  receiver:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

Отправка трейсов и метрик OpenTelemetry Агенту ProtoOBP

• Docker
• Kubernetes

env:
 - name: HOST_IP
   valueFrom:
     fieldRef:
       fieldPath: status.hostIP
 - name: OTEL_EXPORTER_OTLP_ENDPOINT
   value: "http://$(HOST_IP):4317" # GRPC

env:
 - name: HOST_IP
   valueFrom:
     fieldRef:
       fieldPath: status.hostIP
 - name: OTEL_EXPORTER_OTLP_ENDPOINT
   value: "http://$(HOST_IP):4318" # HTTP

env:
  - name: OTEL_SERVICE_NAME
    value: checkout
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: "service.version=3.0.0,service.namespace=shop,deployment.environment.name=prod,team=otel-devs,service_group=otel-demo-3"

Отправка через существующий OpenTelemetry Collector

Если приложения уже отправляют OTLP в свой Collector, добавьте экспортёр ProtoOBP только в pipelines traces и metrics:

exporters:
  otlp_grpc/protoobp:
    endpoint: protoobp.protoobp.svc.cluster.local:4317
    tls:
      insecure: true
    sending_queue:
      batch: {}

service:
  pipelines:
    traces:
      exporters: [debug, otlp_grpc/protoobp]
    metrics:
      exporters: [debug, otlp_grpc/protoobp]
    logs:
      # Agent 7.80.2 не принимает OTLP logs на этом endpoint.
      exporters: [debug]

В Docker Compose используйте DNS-имя контейнера, например endpoint: protoobp-agent:4317. В Kubernetes используйте Service уже развёрнутого Агента. После изменения перезапустите Collector и убедитесь, что в его логах нет DeadlineExceeded, Unimplemented и переполнения очереди.

Логи OpenTelemetry-приложений

Наличие OpenTelemetry SDK не означает, что stdout/stderr контейнера автоматически попадёт в OTLP. Для контейнерных приложений рекомендуемый путь выглядит так:

1. Приложение пишет логи в stdout/stderr.
2. Logs Agent обнаруживает контейнер по Docker label или Kubernetes annotation.
3. Значения service, source, env, version и service_group связывают логи с трейсами и метриками того же сервиса.

Полные примеры для Docker Compose и Kubernetes приведены в разделе «Сбор логов контейнеров».

Примеры подключения OpenTelemetry инструментации

Keycloak

    environment:
      KC_TRACING_ENABLED: true                         # включение инструментации для Keycloak
      KC_TRACING_ENDPOINT: http://protoobp-agent:4317  # адрес агента Proto Observability Platform (для Kubernetes смотри примеры переменных для Java)
      KC_TRACING_SERVICE_NAME: keycloak-otel           # имя сервиса для отображения в интерфейсе Proto Observability Platform

Ingress NGINX Controller

Если вы НЕ используете Ingress-NGINX Helm chart

Для начала убедитесь, что в спецификации пода контроллера Ingress установлена переменная окружения HOST_IP. Если нет, добавьте следующую запись в блок env в спецификации пода:

- name: HOST_IP
  valueFrom:
    fieldRef:
      fieldPath: status.hostIP
- name: OTEL_EXPORTER_OTLP_ENDPOINT
  value: "http://$(HOST_IP):4317"

Затем включите инструментацию OpenTelemetry для контроллера. Создайте или отредактируйте ConfigMap со следующими деталями:

apiVersion: v1
kind: ConfigMap
metadata:
  name: ingress-nginx-controller
  namespace: ingress-nginx
data:
  enable-opentelemetry: "true"
  otel-sampler: AlwaysOn
  otel-service-name: "nginx-ingress" # имя сервиса в ProtoOBP
  otel-sampler-ratio: "0.01"           # уровень сэмплирования трейсов 

Если вы используете Ingress-NGINX Helm chart

Измените файл values.yaml:

controller:
  config:
    enable-opentelemetry: "true"
    otel-service-name: "nginx-ingress"
    otel-sampler: AlwaysOn
    otel-sampler-ratio: 0.01
    exporter_otlp_protocol: grpc
    exporter_otlp_insecure: "true"    
  extraEnvs:
    - name: HOST_IP
      valueFrom:
        fieldRef:
          fieldPath: status.hostIP
    - name: OTEL_EXPORTER_OTLP_ENDPOINT
      value: "http://$(HOST_IP):4317"

Установите или обновите чарт:

helm install my-release ingress-nginx/ingress-nginx -f values.yaml

Инструментация Go через eBPF (AutoSDK)

Go-приложения можно подключить к Proto Observability Platform без изменения кода и без пересборки — с помощью eBPF-агента OpenTelemetry (otel/autoinstrumentation-go). Агент прикрепляется к уже запущенному бинарю, автоматически инструментирует net/http, google.golang.org/grpc, database/sql и github.com/segmentio/kafka-go, а ручные спаны (AutoSDK) собираются без настройки SDK в коде. Телеметрия отправляется в OTLP-приёмник Агента (см. разделы выше).

Подробная инструкция — требования, а также готовая конфигурация для Docker и Kubernetes — на странице инструментации Go: OpenTelemetry AutoSDK (eBPF).