Налаштування виявлення сервісів OBI

Змінні OTEL_EBPF_AUTO_TARGET_EXE, OTEL_EBPF_OPEN_PORT, OTEL_EBPF_AUTO_TARGET_LANGUAGE та OTEL_EBPF_TARGET_PID є змінними середовища, які спрощують налаштування OBI для інструментування одного сервісу або групи повʼязаних сервісів.

В деяких сценаріях OBI інструментує багато сервісів. Наприклад, як Kubernetes DaemonSet, який інструментує всі сервіси на вузлі. Секція YAML discovery дозволяє вказати більш детальні критерії вибору для сервісів, які OBI може інструментувати.

Виявлення сервісів

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

Відриті порти

Вибирає процес для інструментування за портом, який він має відкритим (на якому він слухає). Ця властивість приймає список портів, розділених комами, наприклад 80, і діапазони портів, наприклад 8000-8999. Якщо виконуваний файл відповідає лише одному з портів у списку, OBI вважає це збігом.

Наприклад, вказуючи наступну властивість:

discovery:
  instrument:
    - open_ports: 80,443,8000-8999

OBI вибирає будь-який виконуваний файл, який відкриває порт 80, 443 або будь-який з портів від 8000 до 8999 включно.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Якщо виконуваний файл відкриває кілька портів, вам потрібно вказати лише один з цих портів, щоб OBI інструментував усі HTTP/S та gRPC запити на всіх портах програми. В даний час ви не можете обмежити інструментування лише методами, які надаються через конкретний порт.

Шлях до виконуваного файлу

Вибирає процеси для інструментування за їх шляхом до виконуваного файлу. Ця властивість приймає шаблон для порівняння з повним командним рядком виконуваного файлу, включаючи теку, в якій знаходиться виконуваний файл у файловій системі.

OBI намагається інструментувати всі процеси з шляхом до виконуваного файлу, що відповідає цій властивості. Наприклад, встановлення exe_path: * змушує OBI намагатися інструментувати всі виконувані файли на хості.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Мови програмування

Вибирає процеси за виявленою мовою програмування. Ця властивість приймає шаблон для порівняння з нормалізованими назвами мов, наприклад go, java, python та nodejs.

Наприклад:

discovery:
  instrument:
    - languages: go

Ви також можете поєднувати це з іншими селекторами, наприклад exe_path або open_ports, і всі налаштовані селектори повинні відповідати.

Аргументи командного рядка

Вибирає процеси за аргументами командного рядка. Ця властивість приймає шаблон для порівняння з повним командним рядком процесу.

Наприклад:

discovery:
  instrument:
    - cmd_args: '*--profile=prod*'

Цей селектор можна поєднувати з іншими селекторами в тому ж записі instrument.

Target PIDs

Вибирає процеси за PID. Використовуйте цей селектор, коли ви вже знаєте, які ідентифікатори процесів слід інструментувати.

Наприклад:

discovery:
  instrument:
    - target_pids: [1234, 5678]

Ви також можете налаштувати цільові PID глобально, використовуючи target_pids на кореневому рівні або через OTEL_EBPF_TARGET_PID=1234,5678.

Тільки контейнери

Вибирає процеси для інструментування, які працюють у контейнері OCI. Щоб виконати цю перевірку, OBI перевіряє простір імен мережі процесу та порівнює його зі своїм власним простором імен мережі. Якщо OBI не має достатніх прав для виконання перевірки простору імен мережі, він ігнорує цю опцію.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Імʼя контейнера

Ця властивість селектора обмежує інструментування застосунків, які працюють у контейнерах OCI (таких як Docker) з імʼям, що відповідає наданому шаблону.

Наприклад:

discovery:
  instrument:
    - container_name: '*testserver*'
    - container_name: 'my-app-*'

Цей приклад виявляє всі процеси, що працюють у контейнерах, імена яких містять testserver або починаються з my-app-.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Простір імен K8s

Ця властивість селектора обмежує інструментування застосунків, які працюють у просторах імен Kubernetes з імʼям, що відповідає наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Імʼя Podʼів K8s

Ця властивість селектора обмежує інструментування застосунків, які працюють у Podʼах Kubernetes з імʼям, що відповідає наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Імʼя K8s deployment

Ця властивість селектора обмежує інструментування застосунків, які працюють у Kubernetes Deployments з імʼям, що відповідає наданому шаблону.

Ця властивість селектора обмежує інструментування застосунків, які працюють у Kubernetes Deployments з імʼям, що відповідає наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Імʼя K8s replicaset

Ця властивість селектора обмежує інструментування застосунків, які працюють у Kubernetes ReplicaSets з імʼям, що відповідає наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Імʼя K8s statefulset

Ця властивість селектора обмежує інструментування застосунків, які працюють у Kubernetes StatefulSets з імʼям, що відповідає наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Імʼя K8s daemonset

Ця властивість селектора обмежує інструментування застосунків, які працюють у Kubernetes DaemonSets з імʼям, що відповідає наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Імʼя K8s owner

Ця властивість селектора обмежує інструментування застосунків, які працюють у Podʼах, що належать до Deployment, ReplicaSet, DaemonSet або StatefulSet з імʼям, що відповідає наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Імʼя власника K8s

Ця властивість селектора обмежує інструментування застосунків, які працюють у Podʼах, що належать до Deployment, ReplicaSet, DaemonSet або StatefulSet з імʼям, що відповідає наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Мітки Podʼів K8s

Ця властивість селектора обмежує інструментування застосунків, які працюють у Podʼах з мітками, що відповідають наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Наприклад:

discovery:
  instrument:
    - k8s_namespace: frontend
      k8s_pod_labels:
        instrument: obi

Приклад виявляє всі Podʼи у просторі імен frontend, які мають мітку instrument зі значенням, що відповідає шаблону obi.

Анотації Podʼів K8s

Ця властивість селектора обмежує інструментування застосунків, які працюють у Podʼах з анотаціями, що відповідають наданому шаблону.

Якщо ви вказуєте інші селектори в тому ж запису instrument, процеси повинні відповідати всім властивостям селектора.

Наприклад:

discovery:
  instrument:
    - k8s_namespace: backend
      k8s_pod_annotations:
        obi.instrument: 'true'

Приклад виявляє всі Podʼи у просторі імен backend, які мають анотацію obi.instrument зі значенням, що відповідає шаблону true.

Виключення сервісів з інструментування

Розділ exclude_instrument дозволяє вказати критерії вибору для виключення сервісів з інструментування. Він слідує тому ж формату визначення, як описано в розділі discovery services цього документа.

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

Приклад: Виключення конкретних просторів імен

discovery:
  instrument:
    - k8s_namespace: '*' # Інструментувати всі простори імен
  exclude_instrument:
    - k8s_namespace: development # Виключити простір імен development
    - k8s_namespace: staging # І простір імен staging

Приклад: Виключення сервісів за мітками

discovery:
  rules:
    - match:
        k8s_namespace: production
      exclude:
        k8s_pod_labels:
          skip-instrumentation: 'true'

В цьому прикладі skip-instrumentation — це мітка користувача на Kubernetes Pod. Ви можете використовувати будь-який ключ користувача і значення мітки для отримання збігу або виключення, залежно від домовленостей у вашій організації щодо позначень.

Приклад: Виключення конкретних виконуваних файлів

discovery:
  rules:
    - match:
        open_ports: 80,443,8080
      exclude:
        exe_path: '*prometheus*'
        exe_path: '*grafana*'

Стандартне виключення сервісів з інструментування

Розділ default_exclude_instrument вимикає інструментування самого OBI (самоінструментування), OpenTelemetry Collector та інших компонентів спостереження. Він також вимикає інструментування різних системних просторів імен Kubernetes, щоб зменшити загальні витрати на генерацію метрик. Наступні розділи містять усі виключені компоненти:

• Сервіси, виключені за exe_path: */obi, obi, *otelcol, *otelcol-contrib, *otelcol-contrib[!/]*.
• Сервіси, виключені за k8s_namespace: kube-system, kube-node-lease, local-path-storage, cert-manager, monitoring, gke-connect, gke-gmp-system, gke-managed-cim, gke-managed-filestorecsi, gke-managed-metrics-server, gke-managed-system, gke-system, gke-managed-volumepopulator, gatekeeper-system.

Змініть цю опцію, щоб дозволити OBI інструментувати себе або деякі з інших виключених компонентів.

Примітка: щоб увімкнути таку самоінструментування, вам все ще потрібно включити їх у розділ instrument, або Ці компоненти повинні бути частиною всеосяжних критеріїв включення.

Приклад: Увімкнення інструментування для простору імен, який стандартно виключений

Для увімкнення інструментування для простору імен, який стандартно виключений (наприклад, monitoring), вам потрібно одночасно видалити його зі стандартних виключень та додати до розділу instrument.

Наступний приклад увімкне інструментування для простору імен monitoring:

discovery:
  # Включити простір імен monitoring у інструментування
  instrument:
    - k8s_namespace: monitoring

  # Перевизначити стандартні виключення, щоб видалити простір імен monitoring
  # Цей список зберігає інші стандартні виключення, але видаляє monitoring
  default_exclude_instrument:
    - exe_path: '{*/obi,obi,*otelcol,*otelcol-contrib,*otelcol-contrib[!/]*}'
    - k8s_namespace: kube-system
    - k8s_namespace: kube-node-lease
    - k8s_namespace: local-path-storage
    - k8s_namespace: cert-manager
    # простір імен monitoring видалено з цього списку
    - k8s_namespace: gke-connect
    - k8s_namespace: gke-gmp-system
    - k8s_namespace: gke-managed-cim
    - k8s_namespace: gke-managed-filestorecsi
    - k8s_namespace: gke-managed-metrics-server
    - k8s_namespace: gke-managed-system
    - k8s_namespace: gke-system
    - k8s_namespace: gke-managed-volumepopulator
    - k8s_namespace: gatekeeper-system

Приклад: Вимкнення всіх стандартних виключень

Для вимкнення всіх стандартних виключень і дозволу OBI інструментувати будь-який відповідний сервіс (включаючи себе та інші компоненти спостереження), встановіть default_exclude_instrument як порожній список:

discovery:
  instrument:
    - k8s_namespace: '*' # або вкажіть простір імен чи селектори

  # Порожній список вимикає всі стандартні виключення
  default_exclude_instrument: []

Пропуск специфічних трейсерів Go

Опція skip_go_specific_tracers вимикає виявлення специфіки Go, коли трейсери eBPF перевіряють виконувані файли для інструментування. Трейсер повертається до використання загального інструментування, яке зазвичай є менш ефективним.

Виключення сервісів інструментованих OTel

Опція exclude_otel_instrumented_services вимикає інструментування OBI для сервісів, які вже були інструментовані за допомогою OpenTelemetry. Оскільки OBI часто розгортається для моніторингу всіх сервісів у кластері Kubernetes, моніторинг вже інструментованих сервісів може призвести до дублювання телеметричних даних, якщо ви не обережно розробите критерії вибору (або виключення). Щоб уникнути непотрібних витрат на конфігурацію, OBI моніторить виклики SDK OpenTelemetry для публікації метрик і трейсів, і автоматично вимикає інструментування сервісів, які публікують свої власні телеметричні дані. Вимкніть цю опцію, якщо ваші телеметричні дані, згенеровані застосунком, не конфліктують з даними, згенерованими OBI.

Перевизначення імені та простору імен сервісу

Якщо ви експортуєте дані інструментування через OpenTelemetry або Prometheus, OBI дотримується домовленості іменування сервісів з оператора OpenTelemetry для покращення взаємодії з іншими рішеннями для інструментування.

OBI використовує такі критерії в цьому порядку для автоматичного встановлення імені та простору імен сервісу:

1. Атрибути ресурсу встановлені через OTEL_RESOURCE_ATTRIBUTES та OTEL_SERVICE_NAME змінні середовища процесу або контейнера, що інструментується.
2. У Kubernetes атрибути ресурсу встановлені через такі анотації Pod:
   • resource.opentelemetry.io/service.name
   • resource.opentelemetry.io/service.namespace
3. У Kubernetes атрибути ресурсу встановлені через такі мітки Pod:
   • app.kubernetes.io/name встановлює імʼя сервісу
   • app.kubernetes.io/part-of встановлює простір імен сервісу
4. У Kubernetes атрибути ресурсу обчислюються з метаданих власника Pod, у такому порядку (згідно з їх доступністю):
   • k8s.deployment.name
   • k8s.replicaset.name
   • k8s.statefulset.name
   • k8s.daemonset.name
   • k8s.cronjob.name
   • k8s.job.name
   • k8s.pod.name
   • k8s.container.name
5. Виконуване імʼя інструментованого процесу.

Ви можете перевизначити мітки Kubernetes з попереднього пункту 3 через конфігурацію.

У YAML:

attributes:
  kubernetes:
    resource_labels:
      service.name:
        # отримує імʼя сервісу з першої існуючої мітки Pod
        - override-svc-name
        - app.kubernetes.io/name
      service.namespace:
        # отримує простір імен сервісу з першої існуючої мітки Pod
        - override-svc-ns
        - app.kubernetes.io/part-of

Вони приймають список імен анотацій та міток, розділених комами.

Розширений пошук імен сервісів (v0.5.0+)

Починаючи з версії v0.5.0, OBI включає розширене розпізнавання імен сервісів, що забезпечує більш точну ідентифікацію сервісів, особливо в динамічних і розподілених середовищах.

Покращення:

1. Розпізнавання на основі DNS: OBI може розпізнавати імена сервісів за допомогою DNS-запитів, що забезпечує кращу узгодженість з фактичними механізмами виявлення сервісів, які використовуються застосунками.
2. Збагачення метаданих: розширений пошук з декількох джерел метаданих, включаючи контейнерні середовища виконання та платформи оркестрування.
3. Відстеження зʼєднання: краще відстеження комунікації між сервісами шляхом розпізнавання ідентичностей клієнта та сервера.

Як це працює:

Коли OBI виявляє мережеву комунікацію між сервісами, він намагається визначити імена сервісів, використовуючи доступні налаштовані джерела, у такому порядку пріоритетності:

1. Пошук метаданих Kubernetes: перевірка метаданих Pod та власника з API Kubernetes (увімкнено стандартно)
2. Зворотний DNS від eBPF: використання відповідей DNS, отриманих на рівні ядра (опціонально, вимагає OTEL_EBPF_NAME_RESOLVER_SOURCES=rdns)
3. Стандартний зворотний пошук DNS: виконання зворотних запитів DNS для IP-адрес (опціонально, вимагає OTEL_EBPF_NAME_RESOLVER_SOURCES=dns)

Локальні імена сервісів мають таку ієрархію пріоритетів:

1. Змінна середовища OTEL_SERVICE_NAME (найвищий пріоритет)
2. Змінна середовища OTEL_RESOURCE_ATTRIBUTES (ключ service.name)
3. Анотації імен сервісів (resource.opentelemetry.io/service.name)
4. Мітки імен сервісів (наприклад, app.kubernetes.io/name)
5. Імʼя власника Kubernetes Pod (наприклад, імʼя Deployment) (найнижчий пріоритет)

Це вдосконалення є особливо цінним для:

• Середовищ сервісних мереж: де DNS використовується для маршрутизації сервісів
• Кластери Kubernetes: покращена кореляція з ресурсами Service
• Архітектури мікросервісів: краща візуалізація графіка сервісів з точними назвами сервісів

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

Пошук сервісів на основі метаданих Kubernetes стандартно увімкнено. Щоб увімкнути методи розпізнавання на основі DNS, налаштуйте джерела розпізнавання імен:

# Дозволяє як метадані Kubernetes, так і стандартні зворотні пошуки DNS
export OTEL_EBPF_NAME_RESOLVER_SOURCES=k8s,dns

# Або увімкнути зворотні пошуки DNS, що захоплюються eBPF (потребує захоплення подій DNS)
export OTEL_EBPF_NAME_RESOLVER_SOURCES=k8s,rdns

# Дозволяє всі джерела розпізнавання
export OTEL_EBPF_NAME_RESOLVER_SOURCES=k8s,dns,rdns

# Опціонально: Налаштування розміру кешу (типово: 1024)
export OTEL_EBPF_NAME_RESOLVER_CACHE_LEN=2048

# Опціонально: Налаштування часу життя кешу (типово: 5 хвилин)
export OTEL_EBPF_NAME_RESOLVER_CACHE_TTL=10m

В середовищі Kubernetes переконайтесь що:

• Мережеві політики дозволяють запити DNS (якщо використовується розпізнавання на основі DNS)
• CoreDNS або подібний сервіс DNS працює
• У випадку використання RDNS, застосунки eBPF можуть захоплювати події DNS

Переваги:

• Точніший граф сервісів: спілкування service-to-service показує справжні імена сервісів замість їх IP
• Краща кореляція з трасуваннями: трасування показують назви сервісів, що відповідають вашому каталогу сервісів
• Простіше розвʼязання проблем: визначення сервісу з яким відбувається спілкування не вимагає ручного пошуку IP

Приклад:

Без покращеного пошуку, ви можете побачити:

service.name: "10.0.1.42"
peer.service: "10.0.2.15"

З покращеним пошуком:

service.name: "frontend"
peer.service: "backend-api"