Налаштування експорту даних OBI Prometheus та OpenTelemetry

OBI може експортувати метрики та трейси OpenTelemetry до точки доступу OTLP.

Загальна конфігурація метрик

Розділ YAML: metrics.

Розділ metrics містить загальну конфігурацію для експортерів метрик та трасування OpenTelemetry.

Наразі він підтримує вибір різних наборів метрик для експорту.

Приклад:

metrics:
  features: ['network', 'network_inter_zone']

Обʼєкти експорту метрик

Експортер метрик OBI може експортувати наступні групи даних метрик для процесів, що відповідають записам у конфігурації metrics discovery.

• all або *: Усі групи метрик (зручна опція для увімкнення всіх метрик)
• application: Метрики на рівні застосунку.
• application_host: Метрики хосту на рівні застосунку для тарифікації на основі хосту.
• application_span: метрики відрізків трасування на рівні застосунку в застарілому форматі (наприклад, traces_spanmetrics_latency); spanmetrics не є окремим.
• application_span_otel: метрики відрізків трасування на рівні застосунку в форматі OpenTelemetry (наприклад, traces_span_metrics_calls_total); span_metrics є окремим.
• application_span_sizes: метрики відрізків трасування на рівні застосунку, що повідомляють інформацію про розміри запитів і відповідей.
• application_service_graph: метрики графіків сервісів на рівні застосунку. Рекомендується використовувати DNS для виявлення сервісів і переконатися, що імена DNS відповідають іменам сервісів OpenTelemetry, які використовує OBI. У середовищах Kubernetes найкращим вибором для метрик графіків сервісів є імʼя сервісу OpenTelemetry, встановлене виявленням імені сервісу.
• network: Метрики на рівні мережі. Для отримання додаткової інформації див. документацію з конфігурації мережевих метрик.
• network_inter_zone: Метрики міжзональних мереж. Для отримання додаткової інформації див. документацію з конфігурації мережевих метрик.

Функції експорту метрик для кожного застосунку

Крім того, OBI дозволяє перевизначити глобальні функції експорту метрик на рівні кожного застосунку, додавши metrics > features як властивість до кожного запису discovery > instrument.

Наприклад, у наступній конфігурації:

• Екземпляри сервісів apache, nginx і tomcat експортуватимуть лише метрики application_service_graph (як визначено у глобальній конфігурації metrics > features).

• Сервіс pyserver експортуватиме лише групу метрик application.

• Сервіси, що прослуховують порти 3030 або 3040, експортуватимуть групи метрик application, application_span і application_service_graph.

metrics:
  features: ['application_service_graph']
discovery:
  instrument:
    - open_ports: 3030,3040
      metrics:
        features:
          - 'application'
          - 'application_span'
          - 'application_service_graph'
    - name: pyserver
      open_ports: 7773
      metrics:
        features:
          - 'application'
    - name: apache
      open_ports: 8080
    - name: nginx
      open_ports: 8085
    - name: tomcat
      open_ports: 8090

Компонент експорту метрик OpenTelemetry

Секція YAML: otel_metrics_export

Увімкніть компонент експорту метрик OpenTelemetry, встановивши атрибут endpoint у вашому конфігураційному файлі або через змінну середовища, зверніться до опцій конфігурації експорту метрик.

Налаштуйте компонент у секції otel_metrics_export вашого YAML-конфігураційного файлу або через змінні середовища.

На додачу до конфігурації, задокументованої в цій статті, компонент підтримує змінні середовища з стандартної конфігурації експортерів OpenTelemetry.

Наприклад:

otel_metrics_export:
  ttl: 5m
  endpoint: http://otelcol:4318
  protocol: grpc
  buckets:
    duration_histogram: [0, 1, 2]
  histogram_aggregation: base2_exponential_bucket_histogram

Протокол експорту метрик

Якщо ви не встановите протокол, OBI встановлює протокол наступним чином:

• grpc: якщо порт закінчується на 4317, наприклад 4317, 14317 або 24317.
• http/protobuf: якщо порт закінчується на 4318, наприклад 4318, 14318 або 24318.

Метрики інструментації

Список областей інструментації, з яких OBI може збирати дані:

• *: всі інструментації, якщо * присутній, OBI ігнорує інші значення
• http: HTTP/HTTPS/HTTP/2 метрики застосунків
• grpc: gRPC метрики застосунків
• sql: SQL метрики викликів клієнтів бази даних (включаючи PostgreSQL, MySQL та драйвери Go database/sql такі як pgx)
• redis: Redis метрики клієнтів/серверів бази даних
• kafka: Kafka метрики клієнтів/серверів черг повідомлень
• mqtt: MQTT метрики повідомлень publish/subscribe (MQTT 3.1.1 та 5.0)
• couchbase: Метрики запитів Couchbase N1QL/SQL++ та протоколу метрик KV (Key-Value), що базується на протоколі memcached
• genai: GenAI метрики клієнтів (OpenAI та Anthropic)
• gpu: метрики продуктивності GPU
• mongo: метрики викликів клієнтів MongoDB
• dns: метрики DNS-запитів

Наприклад, встановлення параметра instrumentations на: http,grpc дозволяє збір метрик HTTP/HTTPS/HTTP2 та gRPC застосунків і відключає інші інструментації.

Компонент експортерів трейсів OpenTelemetry

Секція YAML: otel_traces_export

Ви можете налаштувати компонент в секції otel_traces_export вашої YAML конфігурації або через змінні середовища.

На додачу до конфігурації, задокументованої в цій статті, компонент підтримує змінні середовища з стандартної конфігурації експортерів OpenTelemetry.

otel_traces_export:
  endpoint: http://jaeger:4317
  protocol: grpc
  instrumentations: ["http, "sql"]

Протокол експорту трейсів

Якщо ви не встановите протокол, OBI встановлює протокол наступним чином:

• grpc: якщо порт закінчується на 4317, наприклад 4317, 14317 або 24317.
• http/protobuf: якщо порт закінчується на 4318, наприклад 4318, 14318 або 24318.

Інструментування трейсів

Список областей інструментації, з яких OBI може збирати дані:

• *: вся інструментація, якщо * присутній, OBI ігнорує інші значення
• http: HTTP/HTTPS/HTTP/2 трейси застосунків
• grpc: gRPC трейси застосунків
• sql: SQL метрики бази даних клієнтських викликів (включаючи PostgreSQL, MySQL та драйвери Go database/sql такі як pgx)
• redis: Redis трейси клієнтів/серверів бази даних
• kafka: Kafka трейси клієнтів/серверів черг повідомлень
• mqtt: MQTT трейси повідомлень publish/subscribe (MQTT 3.1.1 та 5.0)
• couchbase: Трейси запитів Couchbase N1QL/SQL та трейси протоколу KV (Key-Value), з текстом запиту та деталями операцій
• genai: GenAI трейси клієнтів (OpenAI та Anthropic)
• gpu: GPU трейси продуктивності
• mongo: MongoDB трейси викликів клієнтів
• dns: DNS трейси запитів

Наприклад, якщо ви встановите параметр instrumentations на: http,grpc, це дозволить збір трейсів застосунків HTTP/HTTPS/HTTP2 та gRPC, а також відключить інші інструментації.

Інструментування MQTT

OBI автоматично інструментує MQTT-комунікації, полегшений протокол повідомлень, який зазвичай використовується в IoT та embedded-системах.

Підтримувані операції:

• publish: повідомлення додається до теми
• subscribe: запити на підписку на теми

Версії протоколу:

• MQTT 3.1.1
• MQTT 5.0

Що відстежується:

• Назви тем (обмежуються першим фільтром тем для операцій subscribe)
• Затримка операцій
• Патерни взаємодії клієнт-сервер

Обмеження:

• Для операцій subscribe, використовується тільки перший фільтр тем
• Вміст повідомлень не аналізується, щоб не збільшувати накладні витрати

Приклад використання: Моніторинг публікування даних датчиків шлюзу IoT до брокера MQTT, відстеження швидкості доставки повідомлень та виявлення проблем зі звʼязком.

Інструментування драйвера PostgreSQL pgx

OBI надає спеціалізоване інструментування для pgx, високопродуктивного нативного драйвера Go баз даних PostgreSQL.

Що робить pgx особливим: інструментування pgx підключається безпосередньо до драйвера Go за допомогою специфічного для Go трасування eBPF, забезпечуючи спостережуваність для бази даних без накладних витрат, повʼязаних з загальним інструментуванням SQL мережевого рівня.

Підтримувані операції:

• Query: виконання SQL-запиту з результатами
• Пул зʼєднань (через pgxpool)
• Як нативний pgx API так й інтерфейс обгортка database/SQL

Що відстежується:

• Текст SQL-запиту
• Імʼя хосту сервера PostgreSQL (отримане з конфігурації зʼєднання pgx)
• Тривалість операції та деталі помилок
• Всі стандартні мітки метрик database/SQL

Підтримувані версії pgx: pgx v5.0.0 та новіші (перевірено до версії v5.8.0). Також підтримується через обгортку database/SQL: github.com/jackc/pgx/v5/stdlib

Інструментування Couchbase

Couchbase — це NoSQL база даних документів, що підтримує як безпосередній доступ до ключів-значень так і SQL-подібні запити через SQL++, що широко використовується для застосунків з гнучкими схемами та вимогами до високої доступності. OBI інструментує операції Couchbase через два протоколи:

• Протокол KV (Key-Value): бінарний протокол для безпосереднього доступу через порт 11210, заснований на розширенні Memcached Binary Protocol.
• SQL++ (N1QL): протокол запитів на базі HTTP через порт 8093 до точки доступу /query/service.

KV (Key-Value) protocol

Що відстежується:

Відстеження bucket, scope та collection: Couchbase використовує ієрархічний простір імен: Bucket → Scope → Collection. На відміну від протоколів де простір імен встановлюється для запитів, тут простір імен встановлюється на рівні зʼєднання:

• SELECT_BUCKET (не відстежується): Встановлює активний кошик для всіх наступних операцій для зʼєднання. Подібно до USE database в MySQL чи SELECT db_number в Redis.
• GET_COLLECTION_ID (не відстежується): Перетворює шлях scope.collection в числовий ідентифікатор колекції. OBI використовує його для збагачення атрибутів відрізків областю дії та назвами колекцій.

OBI підтримує кеш імен кошиків, областей дії та колекцій для кожного зʼєднання і використовує його для анотування кожного наступного відрізка.

Обмеження:

• Якщо SELECT_BUCKET відбувається до запуску OBI, ім’я кошика для цього зʼєднання невідоме
• Якщо GET_COLLECTION_ID відбувається до запуску OBI, імʼя колекції недоступне
• Операції автентифікації та метаданих не фіксуються
• Ці обмеження впливають лише на зʼєднання, встановлені до ініціалізації OBI

Операції SQL++ (N1QL) operations

Запити SQL++ (сучасна назва для мови запитів N1QL) визначаються автоматично через порт сервісу HTTP запитів Couchbase 8093 у точці доступу /query/service.

Підтримувані операції:

• Усі типи запитів SQL++: SELECT, INSERT, UPDATE, DELETE, UPSERT
• Операції з кошиками та колекціями, доступ до яких здійснюється через шляхи SQL (наприклад, bucket.scope.collection)
• Запити між колекціями та кошиками

Що відстежується:

Підтримувані бази даних:

• Couchbase Server: виявляється через заголовок версії N1QL у відповіді
• Інші реалізації SQL++: Apache AsterixDB та сумісні бази даних також підтримуються з загальним позначенням other_sql

Формати запитів: SQL++ запити приймаються як JSON body так і form-encoded POST до /query/service:

• JSON Body
• Form Encoded

{
  "statement": "SELECT * FROM `bucket`.`scope`.`collection` WHERE id = $1",
  "query_context": "default:`bucket`.`scope`"
}

statement=SELECT+*+FROM+users&query_context=default:`travel-sample`.`inventory`

Визначення простору імен: Парсер видобуває bucket і collection з:

1. Шляху до таблиці в операторі SQL: `bucket`.`scope`.`collection`
2. Поля query_context, якщо воно присутнє
3. Одного ідентифікатора: розглядається як ім’я колекції (з query_context) або ім’я bucket (без query_context, у старій версії)

Конфігурація: Інструментування SQL++ вимагає явного ввімкнення:

export OTEL_EBPF_HTTP_SQLPP_ENABLED=true
export OTEL_EBPF_BPF_BUFFER_SIZE_HTTP=2048  # Більше за стандартне значення; потрібно для захоплення тіла запиту/відповіді

Обмеження:

• Для виявлення кошиків і колекцій у запиті необхідна нотація шляху SQL (наприклад, bucket.scope.collection) або поле query_context у запиті
• Відповіді без заголовка версії Couchbase позначаються як загальні операції other_sql

Приклад використання: Моніторинг вебзастосунку з високим трафіком, що використовує Couchbase для зберігання сесій та управління контентом, відстеження продуктивності запитів та виявлення неефективних запитів N1QL.

Компонент експортера Prometheus

Секція YAML: prometheus_export

Ви можете налаштувати компонент в секції prometheus_export вашої YAML конфігурації або через змінні середовища. Цей компонент відкриває точку доступу HTTP в інструменті автоматичного інструментування, який дозволяє будь-якому зовнішньому скреперу отримувати метрики у форматі Prometheus. Він активується, якщо встановлено властивість port.

prometheus_export:
  port: 8999
  path: /metrics
  extra_resource_attributes: ['deployment_environment']
  ttl: 1s
  buckets:
    request_size_histogram: [0, 10, 20, 22]
    response_size_histogram: [0, 10, 20, 22]
  instrumentations: ['http', 'sql']

Додаткові атрибути ресурсів Prometheus

Через обмеження внутрішнього клієнта API Prometheus, OBI потрібно заздалегідь знати, які атрибути відкриті для кожної метрики. Це призведе до того, що деякі атрибути, які виявляються під час виконання, під час інструментації, не будуть стандартно видимими. Наприклад, атрибути, визначені для кожного застосунку через анотації Kubernetes або в змінній середовища OTEL_RESOURCE_ATTRIBUTES цільового застосунку.

Наприклад, застосунок, що визначає OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production як змінну середовища, атрибут target_info{deployment.environment="production"} буде стандартно видимий, якщо метрики експортуються через OpenTelemetry, але не якщо вони експортуються через Prometheus.

Щоб зробити deployment_environment видимим у Prometheus, вам потрібно додати його до списку extra_resource_attributes.

Інструментація Prometheus

Список областей інструментування, з яких OBI може збирати дані:

• *: всі області інструментування, якщо * присутній, OBI ігнорує інші значення
• http: метрики застосунків HTTP/HTTPS/HTTP/2
• grpc: метрики застосунків gRPC
• sql: метрики викликів клієнтів SQL бази даних (включаючи PostgreSQL, MySQL та драйвери Go database/sql такі як pgx)
• redis: метрики клієнтів/серверів Redis бази даних
• kafka: метрики клієнтів/серверів Kafka черг повідомлень
• mqtt: метрики повідомлень publish/subscribe
• couchbase: Метрики запитів Couchbase N1QL/SQL++ та протоколу метрик KV (Key-Value)
• genai: Метрики клієнтів GenAI (OpenAI та Anthropic)

Наприклад, якщо встановити параметр instrumentations на: http,grpc, це дозволить збір метрик застосунків HTTP/HTTPS/HTTP2 і gRPC, а також вимкне інші області інструментування.