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

Подключение трейсинга c помощью OpenTelemetry.

Введение

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

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

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

Включение поддержки 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. Это позволяет подключаться с любого сетевого интерфейса.

Для gRPC по умолчанию используется порт 4317:

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

Для HTTP порт по умолчанию 4318:

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

В качестве альтернативы можно настроить эндпоинты, указав порт в переменных окружения:

Для gRPC:

POBP_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT=0.0.0.0:4317

Для HTTP:

POBP_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT=0.0.0.0:4318

Добавьте переменные окружения к контейнеру с ProtoOBP Агентом:
- Для gRPC:
```
POBP_OTLP_CONFIG_RECEIVER_PROTOCOLS_GRPC_ENDPOINT: 0.0.0.0:4317
```
- Для HTTP:
```
POBP_OTLP_CONFIG_RECEIVER_PROTOCOLS_HTTP_ENDPOINT: 0.0.0.0:4318
```
Убедитесь, что порты 4317 и 4318 у контейнера открыты/подключены к хосту.

Включите эндпоинты OTLP на агенте, отредактировав секцию protoobp.otlp в файле values.yaml Helm чарта:

Для gRPC:

protoobp:
...
  otlp:
    receiver:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
          enabled: true

Для HTTP:

protoobp:
...    
  otlp:
    receiver:
      protocols:
        http:
          endpoint: 0.0.0.0:4318
          enabled: true

Есть чарт уже был применен, обновите его, чтобы новые параметры применились, например:
```
helm upgrade protoobp -f values.yaml protoobp/protoobp --namespace protoobp
```

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

Для контейнера с приложением установите переменную окружения OTEL_EXPORTER_OTLP_ENDPOINT так, чтобы она указывала на контейнер с Агентом. Например:

HTTP
```
OTEL_EXPORTER_OTLP_ENDPOINT=http://protoobp-agent:4318  # HTTP
```
GRPC
```
OTEL_EXPORTER_OTLP_ENDPOINT=http://protoobp-agent:4317  # GRPC
```
Убедитесь, что оба контейнера (с приложением и Агентом) находятся в одной и той же Docker сети, чтобы порт Агента был доступен для контейнера с приложением.

В файле деплоймента приложения укажите эндпоинт, который будет использоваться OpenTelemetry клиентом для отсылки трейсов с помощью переменной окружения OTEL_EXPORTER_OTLP_ENDPOINT.

Для gRPC:

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

Для HTTP:

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

Примеры подключения 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