OBI як приймач Колектора OpenTelemetry

Дізнайтеся, як використовувати OBI як приймач даних в OpenTelemetry Колектор для централізованої обробки телеметричних даних.

Починаючи з версії v0.5.0, OBI може працювати як компонент-приймач у рамках OpenTelemetry Collector. Ця інтеграція дозволяє використовувати потужний конвеєр обробки Collector, одночасно користуючись перевагами інструментування eBPF OBI без коду.

Огляд

Використання OBI як приймача Collector поєднує переваги обох інструментів:

Від OBI:

  • Інструментування без коду з використанням eBPF
  • Автоматичне виявлення сервісів
  • Низькі накладні витрати на спостереження

Від OpenTelemetry Collector:

  • Уніфікований конвеєр телеметрії
  • Різноманітні процесори (вибірка, фільтрування, перетворення)
  • Кілька експортерів (бекенди, формати)
  • Централізована конфігурація

Коли використовувати режим приймача колектора

Приклади ефективного використання

  • Централізована обробка: ви хочете, щоб усі телеметричні дані проходили через єдиний конвеєр
  • Складна обробка: потрібні розширені функції вибірки, фільтрування або збагачення, які надає колектор
  • Кілька бекендів: надсилання даних на кілька платформ спостереження
  • Вимоги до відповідності: необхідна обробка телеметрії для редагування даних або видалення PII
  • Спрощене розгортання: єдиний бінарний файл замість окремих процесів OBI + Collector

Коли використовувати замість цього окремий OBI

  • Прості розгортання: достатньо прямого експорту до одного бекенду
  • Edge середовища: обмежені ресурси, де запуск повного Collector є занадто важким
  • Тестування/розробка: швидке налаштування без конфігурації Collector

Порівняння архітектури

Автономний OBI

graph TD
    App[Застосунок]
    OBI[Інструментування<br/> OBI eBPF]
    Backend[Бекенд]

    App --> OBI
    OBI -->|OTLP| Backend

OBI як приймач колектора

graph TD
    App[Застосунок]

    subgraph Collector[OpenTelemetry Collector]
        OBI[Приймач OBI<br/>Інчструментування eBPF]
        Processors[Процесори<br/>вибірка, фільтрування, збагачення]
        Exporters[Експортери<br/>кілька бекендів]
    end

    Backend1[Бекенд 1]
    Backend2[Бекенд 2]
    Backend3[Бекенд 3]

    App --> OBI
    OBI --> Processors
    Processors --> Exporters
    Exporters --> Backend1
    Exporters --> Backend2
    Exporters --> Backend3

Конфігурація

Створення власного колектора з приймачем OBI

Для використання OBI як приймача колектора вам потрібно створити власний бінарний файл колектора, який включає компонент приймача OBI. Це робиться за допомогою OpenTelemetry Collector Builder (OCB), інструменту, який генерує власний бінарний файл колектора з вашими вказаними компонентами. Якщо у вас не встановлено OCB, див. інструкції з встановлення.

Вимоги:

  • Go 1.25 чи новіше
  • OCB встановлено і він доступний у вашій змінній PATH
  • Локальна копія репозиторію OpenTelemetry eBPF Instrumentation версії v0.5.0 чи новіше
  • Docker (для створення файлів eBPF) або компілятор C, clang, та заголовки eBPF

Кроки створення:

  1. Згенеруйте файли eBPF у вашій локальній теці з сирцями OBI:

    cd /path/to/obi
make docker-generate
# або, якщо у вас встановлено локально build tools:
# make generate

    Цей крок має бути виконаний перед збіркою за допомогою ocb. Він генерує необхідні типи привʼязок eBPF, які потрібні приймачу OBI.

  2. Створіть builder-config.yaml:

    dist:
  name: otelcol-obi
  description: OpenTelemetry Collector with OBI receiver
  output_path: ./dist

exporters:
  - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.142.0
  - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.142.0

processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.142.0

receivers:
  - gomod: go.opentelemetry.io/obi v0.5.0
    import: go.opentelemetry.io/obi/collector

providers:
  - gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.18.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.18.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpprovider v1.18.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpsprovider v1.18.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/yamlprovider v1.18.0

replaces:
  - go.opentelemetry.io/obi => /path/to/obi

    Замініть /path/to/obi на відповідний шлях до теки де знаходяться ваші сирці OBI. Секція replaces: говорить ocb що потрібно використовувати локальні сирці OBI замість того щоб викачувати їх з загального публічного репо, що є потрібним оскільки опублікований моду OBI не включає згенерований код BPF.

    Вибір версії: Вам треба вказати версію для кожного компонента. В нашому прикладі вище використовуються версії що є сумісними з OBI v0.5.0. Якщо ви використовуєте іншу версію OBI або бажаєте використовувати новіші версії компонентів, перевірте файл go.mod у вашому репозиторії OBI, щоб побачити, від яких версій компонентів колектора він залежить, а потім оновіть версії у вашому конфігураційному файлі builder відповідно.

  3. Зберіть власний Collector:

    ocb --config builder-config.yaml

    Скомпільований двійковий файл буде знаходитись у ./dist/otelcol-obi.

Конфігурація колектора з приймачем OBI

Створіть конфігураціюOpenTelemetry Collector, що включає приймач OBI:

# collector-config.yaml
receivers:
  # Приймач OBI для інструментування eBPF
  obi:
    # Слухати порт 9999 для інструментування HTTP трафіку
    open_port: '9999'

    # Вмикає збір метрік обʼєктів мережі та застосунка
    meter_provider:
      features: [network, application]

    # Опціонально: конфігурація виявлення Сервісів
    # discovery:
    #   poll_interval: 30s

processors:
  # Пакетна обробка телеметрії для покращення ефективності
  batch:
    timeout: 1s
    send_batch_size: 1024

exporters:
  # Локальний експорт трейсів для відлагодження
  debug:
    verbosity: detailed

  # Експорт до загального бекенду OTLP
  otlp:
    endpoint: https://backend.example.com:4317
    headers:
      api-key: ${env:OTLP_API_KEY}

service:
  pipelines:
    # Конвеєр трейсів з інструментуваннями OBI
    traces:
      receivers: [obi]
      processors: [batch]
      exporters: [debug, otlp]

    # Конвеєр метрік
    metrics:
      receivers: [obi]
      processors: [batch]
      exporters: [debug, otlp]

Запуск колектора

sudo ./otelcol-obi --config collector-config.yaml

OBI вимагає розширених привілеїв для інструментування процесів з використанням eBPF. Колектор потрібно запускати через sudo або мати відповідні Linux capabilities (CAP_SYS_ADMIN, CAP_DAC_READ_SEARCH, CAP_NET_RAW, CAP_SYS_PTRACE, CAP_PERFMON, CAP_BPF) для:

  • Приєднання проб eBPF до процесів, що працюють
  • Доступу до памʼяті процесів та системної інформації
  • Встановлення блокування памʼяті для програм eBPF
  • Захоплення мережевої телеметрії та телеметрії застосунків

Без цих дозволів OBI не зможе інструментувати процеси та зазнає збою під час запуску.

Порівняння функцій: Режим приймача та самостійна робота

ФункціяСамостійний OBIOBI як приймач
eBPF instrumentation✅ Yes✅ Yes
Service discovery✅ Yes✅ Yes
Traces collection✅ Yes✅ Yes
Metrics collection✅ Yes✅ Yes
JSON log enrichment✅ Yes✅ Yes
Direct OTLP export✅ Yes❌ No (via Collector)
Collector processors❌ No✅ Yes
Multiple exporters⚠️ Limited✅ Full support
Tail sampling for traces❌ No✅ Yes
Data transformation⚠️ Basic✅ Advanced
Resource overheadLowerModerate
Configuration complexitySimpleMore complex
Single binary deployment✅ Yes✅ Yes

Розширені налаштування

Розгортання Kubernetes DaemonSet з кількома просторами імен

Для розгортання Колектора з приймачем OBI на кожному вузлі, вам потрібно додати власний двійковий файл колектора до образу контейнера:

  1. Створіть Dockerfile:

    FROM alpine:latest

# Встановлення потрібних інструментів
RUN apk --no-cache add ca-certificates

# Копіюємо власний двійковий файл колектора, створений за допомогою OCB
COPY dist/otelcol-obi /otelcol-obi

# Даємо права на виконання
RUN chmod +x /otelcol-obi

ENTRYPOINT ["/otelcol-obi"]

  2. Створюємо та публікуємо образ:

    docker build -t my-registry/otelcol-obi:v0.5.0 .
docker push my-registry/otelcol-obi:v0.5.0

  3. Розгортаємо DaemonSet:

    # otel-collector-daemonset.yaml
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: otel-collector-obi
  namespace: monitoring
spec:
  selector:
    matchLabels:
      app: otel-collector-obi
  template:
    metadata:
      labels:
        app: otel-collector-obi
    spec:
      hostNetwork: true
      hostPID: true
      containers:
        - name: otel-collector
          image: my-registry/otelcol-obi:v0.5.0
          args:
            - --config=/conf/collector-config.yaml
          securityContext:
            privileged: true
            capabilities:
              add:
                - SYS_ADMIN
                - SYS_PTRACE
                - NET_RAW
                - DAC_READ_SEARCH
                - PERFMON
                - BPF
                - CHECKPOINT_RESTORE
          volumeMounts:
            - name: config
              mountPath: /conf
            - name: sys
              mountPath: /sys
              readOnly: true
            - name: proc
              mountPath: /host/proc
              readOnly: true
          resources:
            limits:
              memory: 1Gi
              cpu: '1'
            requests:
              memory: 512Mi
              cpu: 500m
      volumes:
        - name: config
          configMap:
            name: otel-collector-config
        - name: sys
          hostPath:
            path: /sys
        - name: proc
          hostPath:
            path: /proc

Прибираємо чутливі дані

Для використання цієї конфігурації вам потрібно додати процесори attributes та filter до вашого builder-config.yaml:

processors:
  - gomod:
      github.com/open-telemetry/opentelemetry-collector-contrib/processor/attributesprocessor
      v0.142.0
  - gomod:
      github.com/open-telemetry/opentelemetry-collector-contrib/processor/filterprocessor
      v0.142.0

Далі використовувати процесори Колектора для прибирання чутливих даних перед експортом:

receivers:
  obi:
    discovery:
      poll_interval: 30s

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

  # Прибираємо чутливі дані
  attributes:
    actions:
      - key: http.url
        action: delete
      - key: user.email
        action: delete
      - key: credit_card
        pattern: \d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}
        action: hash

  # Видаляємо відрізки з чутливими операціями
  filter:
    traces:
      span:
        - attributes["operation"] == "process_payment"
        - attributes["internal"] == true

exporters:
  debug:
    verbosity: detailed

  # Експорт до бекенду OTLP
  otlp:
    endpoint: backend.example.com:4317

service:
  pipelines:
    traces:
      receivers: [obi]
      processors: [attributes, filter, batch]
      exporters: [debug, otlp]

Вибірка наприкінці

Реалізуйте інтелектуальну вибірку за допомогою Колектора. Цей приклад вимагає процесора tail_sampling з contrib. Додайте його до вашого builder-config.yaml:

processors:
  - gomod:
      github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor
      v0.142.0

Приклад налаштувань:

receivers:
  obi:
    open_port: '9999'

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

  # Вибірка на прикінці залишає:
  # - Всі трасування з помилками
  # - Повільні трасування (> 1s)
  # - 5% успішних швидких трасувань
  tail_sampling:
    policies:
      - name: errors
        type: status_code
        status_code:
          status_codes: [ERROR]
      - name: slow_traces
        type: latency
        latency:
          threshold_ms: 1000
      - name: sample_success
        type: probabilistic
        probabilistic:
          sampling_percentage: 5

exporters:
  debug:
    verbosity: detailed

  otlp:
    endpoint: backend.example.com:4317

service:
  pipelines:
    traces:
      receivers: [obi]
      processors: [tail_sampling, batch]
      exporters: [debug, otlp]

Зауваження щодо продуктивності

Використання ресурсів

Використання ресурсів для OBI як приймача Collector значно варіюється в залежності від:

  • Обсягу телеметрії: кількості інструментованих сервісів та кількості запитів
  • Складності конвеєра: кількості та типу налаштованих процесорів
  • Налаштувань експортерів: розміру пакетів, глибини запитів та кількості бекендів
  • Обсягу виявлення сервісів: кількості процесів робота яких відстежується

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

Рекомендації:

Поради з оптимізації

  1. Використовуйте процесор пакетної обробки: завжди додавайте процесор пакетної обробки для зменшення накладних витрат на експорт

  2. Обмежте кількість процесорів конвеєра: кожен процесор додає затримку та використання CPU

  3. Налаштовуйте буферизацію: підлаштовуйте розмір черги для великих середовищ:

    exporters:
  otlp:
    sending_queue:
      enabled: true
      num_consumers: 10
      queue_size: 5000

  4. Стежте за метриками Колектора: вмикає самомоніторинг Колектора:

    service:
  telemetry:
    metrics:
      address: :8888

Обмеженнях

  • Тільки один вузол: приймач OBI інструментує лише локальні процеси (на тому вузлі де працює Колектор)
  • Потрібен привілейований доступ: колектор має запускатись з можливостями eBPF
  • Працює тільки на Linux: eBPF існує тільки для Linux; Windows та macOS не підтримуються
  • Перезапуск Колектора: зміни в налаштуваннях OBI вимагають перезапуску Колектора

Розвʼязання проблем

Проблеми збірки

Помилка: “API incompatibility” або “unknown revision”

Якщо ви зіткнулись з помилкою несумісності API або помилкою “unknown revision” під час збирання Колектора:

  1. Переконайтесь, що сирці в теці OBI є свіжими:

    cd /path/to/obi
git pull origin main  # або ваша гілка

  2. Переконайтесь, що ви не встановили конкретні версії для компонентів колектора в конфігурації збирання, або що вони відповідають версіям вказаним у файлі go.mod для OBI.

  3. Перевірте ваш файл go.mod OBI, щоб дізнатись від яких версій компонентів він залежить:

    grep "go.opentelemetry.io/collector" go.mod

    Після чого вкажіть тіж самі версії у файлі builder-config.yaml для інших компонентів.

Помилки під час запуску

Помилка: “Required system capabilities not present” або “operation not permitted”

OBI вимагає підвищених привілеїв для роботи. У вас є два варіанти:

Варіант 1: Запуск з sudo (найпростіший)
sudo ./otelcol-obi --config collector-config.yaml
Варіант 2: Наданні можливостей (capabilities) (більш безпечно)

Використовуйте setcap для використання тільки потрібних можливостей:

sudo setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search,cap_net_raw,cap_perfmon,cap_bpf,cap_checkpoint_restore=ep ./otelcol-obi

Після чого виконайте запуск без використання sudo:

./otelcol-obi --config collector-config.yaml

Перевірте, що можливості були надані:

getcap ./otelcol-obi

В Kubernetes:

Переконайтесь що контекст безпеки Пода має відповідні можливості Linux:

securityContext:
  capabilities:
    add:
      - SYS_ADMIN
      - SYS_PTRACE
      - BPF
      - NET_RAW
      - CHECKPOINT_RESTORE
      - DAC_READ_SEARCH
      - PERFMON

Помилка: “failed to create OBI receiver: permission denied”

Ця означає, що у Колектора немає необхідних можливостей. Переконайтесь, що ви запускаєте його з sudo або з правильним контекстом безпеки Kubernetes, показаним вище.

Відсутність телеметрії від інструментованих застосунків

  1. Перевірте налаштування приймача OBI:

    receivers:
  obi:
    discovery:
      poll_interval: 30s
    instrument:
      - exe_path: /path/to/app # чи є цей шлях коректним

  2. Перевірте виявлення сервісів в логах Колектора:

    grep "discovered service" collector.log

  3. Переконайтесь, що eBPF програми завантажуються з використанням bpftool:

    # В контейнері Колектора
bpftool prog show

Значне споживання памʼяті

Причина: Велика кількість телеметрії чи інструментовано забагато процесів

Вирішення:

  1. Встановіть потрібний розмір пакетної обробки для зменшення накладних витрат на пересилання даних:

    processors:
  batch:
    timeout: 200ms
    send_batch_size: 512
    send_batch_max_size: 1024

  2. Будьте більш вибірковими з інструментуванням - інструментуйте обмежену кількість сервісів за допомогою OBI:

    receivers:
  obi:
    instrument:
      targets:
        - service_name: 'web-app'
        - service_name: 'api-service'

    Це допоможе зменшити обсяг телеметрії тільки вказаними сервісами замість всіх процесів.

Міграція з самостійного OBI

Крок 1: Створення власного Колектора

Дивіться розділ конфігурація для побудови Колектора з приймачем OBI.

Крок 2: Конвертація конфігурації OBI

Перетворіть вашу конфігурацію самостійного OBI в формат Колектора:

Самостійний OBI:

# obi-config.yaml
otel_traces_export:
  endpoint: http://backend:4318

open_port: 8080

Колектор з приймачем OBI:

# collector-config.yaml
receivers:
  obi:
    instrument:
      - open_port: 8080

exporters:
  otlp:
    endpoint: backend:4317

service:
  pipelines:
    traces:
      receivers: [obi]
      processors: [batch]
      exporters: [otlp]

Крок 3: Розгортання та перевірка

  1. Зупиніть самостійний OBI
  2. Запустіть Колектор з приймачем OBI
  3. Перевірте потік телеметрії у вашому бекенді

Що далі?


Востаннє змінено December 26, 2024: [uk] Ukrainian documentation for OpenTelemetry (0aab4883)