OpenTelemetry

Prerequisites

Tue, 15 Jul 2025 10:17:31 -0300

To contribute to this repository, you need to be familiar with the following techs and tools:

git
GitHub
Markdown (CommonMark)
YAML

For technical details concerning how the documentation is built and tested locally, see Development.

Sign the CNCF CLA

All OpenTelemetry contributors must sign the Linux Foundation Contributor License Agreement (CLA).

Pull requests from contributors who haven’t signed the CLA fail the automated tests. The name and email you provide must match those found in your git config, and your git name and email must match those used for the CNCF CLA.

Бібліотеки клієнтів Prometheus чи OpenTelemetry

Thu, 26 Dec 2024 22:02:19 +0200

Примітка

Ця сторінка охоплює Java та Go. Приклади для інших мов плануються.

Цей посібник призначений для розробників, знайомих з бібліотеками клієнтів Prometheus, які хочуть зрозуміти еквівалентні шаблони в API та SDK метрик OpenTelemetry. Він охоплює найпоширеніші шаблони, але не є вичерпним.

Концептуальні відмінності

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

Розгортання OBI в Kubernetes

Thu, 26 Dec 2024 22:02:19 +0200

Примітка

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

Налаштування декорування метаданих Kubernetes

OBI може декорувати ваші трейси наступними мітками Kubernetes:

k8s.namespace.name
k8s.deployment.name
k8s.statefulset.name
k8s.replicaset.name
k8s.daemonset.name
k8s.node.name
k8s.pod.name
k8s.container.name
k8s.pod.uid
k8s.pod.start_time
k8s.cluster.name

Щоб увімкнути декорування метаданих, вам потрібно:

Створити ServiceAccount і привʼязати ClusterRole, що надає права list і watch для Pods і ReplicaSets. Ви можете зробити це, розгорнувши цей приклад файлу:

Baggage

Thu, 26 Dec 2024 22:02:19 +0200

В OpenTelemetry Baggage — це контекстна інформація, яка знаходиться поруч з контекстом. Baggage — це сховище ключ-значення, що дозволяє поширювати будь-які дані, які вам подобаються, поряд з контекстом.

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

Приклад

Baggage часто використовується в трасуванні для поширення додаткових даних між сервісами.

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

Логи

Thu, 26 Dec 2024 22:02:19 +0200

Лог — це текстовий запис з часовою міткою, структурований (рекомендовано) або неструктурований, з додатковими метаданими. З усіх сигналів телеметрії, логи мають найбільшу спадщину. Більшість мов програмування мають вбудовані можливості логування або добре відомі, широко використовувані бібліотеки логування.

Логи OpenTelemetry

OpenTelemetry надає API та SDK для створення записів логів, а також SDK для мов та мости для логів для інтеграції з наявними фреймворками логів. Логи — це все, що ви надсилаєте через провайдера логів, а події — це особливий тип логів. Не всі логи є подіями, але всі події є логами. API логів є публічним і може використовуватися безпосередньо кодом програми або опосередковано через наявні бібліотеки та мости логів.

Параметри конфігурації OBI Network Metrics

Thu, 26 Dec 2024 22:02:19 +0200

Мережеві метрики налаштовуються в підрозділі network файлу YAML-конфігурації OBI або за допомогою набору змінних середовища з префіксом OTEL_EBPF_NETWORK_.

Приклад YAML:

network:
 enable: true
 cidrs:
 - 10.10.0.0/24
 - 10.0.0.0/8
 - 10.30.0.0/16
attributes:
 kubernetes:
 enable: true
 select:
 obi_network_flow_bytes:
 include:
 - k8s.src.owner.name
 - k8s.src.namespace
 - k8s.dst.owner.name
 - k8s.dst.namespace
 - src.cidr
 - dst.cidr
otel_metrics_export:
 endpoint: http://localhost:4318

На додачу до розділу network YAML, конфігурація OBI вимагає наявності точки доступу для експорту мережевих метрик (в попередньому прикладі, otel_metrics_export, але вона також приймає точки доступу Prometheus).

Міграція з OpenCensus

Thu, 26 Dec 2024 22:02:19 +0200

Запустіть OBI як контейнер Docker

Thu, 26 Dec 2024 22:02:19 +0200

OBI може запускати автономний контейнер Docker, який може інструментувати процес, що виконується в іншому контейнері.

Образи контейнерів OBI публікуються в обох реєстрах:

Docker Hub: otel/ebpf-instrument:v<версія>
GHCR: ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/ebpf-instrument:v<версія>

Теґ розробки також опубліковано на Docker Hub як:

otel/ebpf-instrument:main

Контейнер OBI повинен бути налаштований наступним чином:

запустіть як привілейований контейнер або як контейнер з можливістю SYS_ADMIN (але цей останній варіант може не працювати в деяких середовищах контейнерів)
Використовуйте простір імен PID host, щоб дозволити доступ до процесів в інших контейнерах.

Підписання та перевірка образів

Образ контейнера OBI підписується за допомогою Cosign з використанням тимчасових ключів, автентифікованих через протокол OIDC (OpenID Connect) в GitHub Actions. Це забезпечує автентичність та цілісність контейнера, опублікованого проєктом OpenTelemetry.

Метрики

Thu, 26 Dec 2024 22:02:19 +0200

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

Метрики застосунків та запитів є важливими показниками доступності та продуктивності. Користувацькі метрики можуть надати уявлення про те, як показники доступності впливають на користувацький досвід або бізнес. Зібрані дані можуть бути використані для сповіщення про збій або запуску рішень щодо планування для автоматичного масштабування розгортання при високому попиті.

Глобальні властивості конфігурації OBI

Thu, 26 Dec 2024 22:02:19 +0200

OBI можна налаштувати через змінні середовища або через файл конфігурації YAML, переданий або з аргументом командного рядка -config, або через змінну середовища OTEL_EBPF_CONFIG_PATH. Змінні середовища мають пріоритет над властивостями у файлі конфігурації. Наприклад, у наступному рядку команди опція OTEL_EBPF_LOG_LEVEL перевизначає будь-які налаштування log_level всередині config.yaml:

Аргумент конфігурації:

OTEL_EBPF_LOG_LEVEL=debug obi -config /path/to/config.yaml

Змінна середовища конфігурації:

OTEL_EBPF_LOG_LEVEL=debug OTEL_EBPF_CONFIG_PATH=/path/to/config.yaml obi

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

OBI складається з конвеєра компонентів, які генерують, перетворюють і експортують трейс з HTTP і gRPC застосунків. У YAML конфігурації кожен компонент має свій власний розділ першого рівня.

Міграція з OpenTracing

Thu, 26 Dec 2024 22:02:19 +0200

Зворотна сумісність з OpenTracing була пріоритетом для проєкту OpenTelemetry з самого початку. Щоб полегшити міграцію, OpenTelemetry підтримує використання як API OpenTelemetry, так і OpenTracing в одному коді. Це дозволяє записувати інструментування OpenTracing за допомогою SDK OpenTelemetry.

Для цього кожен SDK OpenTelemetry надає OpenTracing shim, який діє як міст між API OpenTracing та SDK OpenTelemetry. Зверніть увагу, що OpenTracing shims стандартно вимкнені.

Підтримка версій мов

Перед використанням OpenTracing shim перевірте версії мови та компонентів середовища виконання вашого проєкту та оновіть їх за потреби. Мінімальні мовні версії API OpenTracing та OpenTelemetry наведені в таблиці нижче.

Розгортання OBI в Kubernetes за допомогою Helm

Thu, 26 Dec 2024 22:02:19 +0200

Примітка

Для отримання додаткової інформації про різноманітні параметри конфігурації Helm, ознайомтеся з документацією Helm чарту OBI або дивіться на Artifact Hub. Для отримання докладної інформації про параметри конфігурації дивіться файл values.yaml

Вміст:

Розгортання OBI з Helm
Налаштування OBI
Налаштування метаданих OBI
Надання секретів для конфігурації Helm

Розгортання OBI з Helm

Спочатку потрібно додати репозиторій OpenTelemetry до Helm:

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts

Наступна команда розгортає DaemonSet OBI зі стандартною конфігурацією в просторі obi:

Швидкий старт з отримання мережевих метрик OBI

Thu, 26 Dec 2024 22:02:19 +0200

OBI може генерувати мережеві метрики в будь-якому середовищі (фізичний хост, віртуальний хост або контейнер). Рекомендується використовувати середовище Kubernetes, оскільки OBI може прикрашати кожну метрику метаданими джерела та призначення Kubernetes-обʼєктів.

Інструкції в цьому посібнику швидкого старту зосереджені на безпосередньому розгортанні в Kubernetes за допомогою утиліти командного рядка kubectl. Цей посібник описує, як розгорнути OBI в Kubernetes з нуля. Щоб використовувати Helm, зверніться до документації Розгортання OBI в Kubernetes за допомогою Helm.

Розгортання OBI з мережевими метриками

Щоб увімкнути мережеві метрики, встановіть наступну опцію у вашій конфігурації OBI:

Швидкий старт

Thu, 26 Dec 2024 22:02:19 +0200

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

Примітка

Цей швидкий старт створює базове локальне середовище. Мета полягає в тому, щоб показати, як працює Колектор, а не налаштувати готове до виробництва середовище.

У цьому посібнику ви навчитеся:

Запускати локальний екземпляр OpenTelemetry Колектор
Генерувати дані трейсів і надсилати їх до Колектора
Перевіряти, що Колектор отримує та обробляє дані

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

Трейси

Thu, 26 Dec 2024 22:02:19 +0200

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

Розгляньмо це на прикладі трьох одиниць роботи, представлених як Відрізки:

Примітка

Наступні приклади JSON не представляють конкретний формат, і особливо не OTLP/JSON, який є більш детальним.

Налаштування режимів експорту OBI

Thu, 26 Dec 2024 22:02:19 +0200

У режимі Direct OBI надсилає метрики та трейси безпосередньо до віддаленої точки доступу за допомогою протоколу OpenTelemetry (OTLP).

OBI також може надавати точку доступу HTTP Prometheus, готову до збору, наприклад, у режимі pull.

Для використання режиму Direct потрібна конфігурація з обліковими даними для автентифікації. Встановіть облікові дані автентифікації точки доступу OTLP за допомогою цих змінних середовища:

OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_HEADERS

Щоб запустити в режимі Direct, використовуючи точку доступу збору Prometheus, див. документацію з конфігурації. документація з конфігурації.

Початок роботи

Thu, 26 Dec 2024 22:02:19 +0200

Налаштування

Завантажте opentelemetry-javaagent.jar з Releases репозиторію opentelemetry-java-instrumentation і розмістіть JAR у вашій улюбленій теці. Файл JAR містить агент та бібліотеки інструментування.
Додайте -javaagent:path/to/opentelemetry-javaagent.jar та інші налаштування до аргументів запуску JVM і запустіть ваш застосунок:
- Безпосередньо командою запуску:
```
java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar
```
- Через JAVA_TOOL_OPTIONS та інші змінні середовища:
```
export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="your-service-name"
java -jar myapp.jar
```

Декларативна конфігурація

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

Початок роботи

Thu, 26 Dec 2024 22:02:19 +0200

Ця сторінка проведе вас через найшвидший спосіб почати моніторинг вашого кластера Kubernetes за допомогою OpenTelemetry. Вона зосереджується на зборі метрик та логів для кластерів Kubernetes, вузлів, podʼів та контейнерів, а також на налаштуванні кластера для підтримки сервісів, що передають дані OTLP.

Якщо ви хочете побачити OpenTelemetry в дії з Kubernetes, найкраще місце для початку — це Демо OpenTelemetry. Демо призначене для ілюстрації впровадження OpenTelemetry, але не є прикладом того, як моніторити сам Kubernetes. Після завершення цього керівництва, цікавим експериментом може бути встановлення демо та спостереження за тим, як весь моніторинг реагує на активне навантаження.

Вимірювання трафіку між зонами доступності хмари

Thu, 26 Dec 2024 22:02:19 +0200

Примітка

Ця функція наразі доступна лише в кластерах Kubernetes.

Трафік між зонами доступності хмари може призвести до додаткових витрат. OBI може вимірювати його, або додаючи атрибути src.zone та dst.zone до регулярних мережевих метрик, або надаючи окрему метрику obi.network.inter.zone.bytes (OTel) / obi_network_inter_zone_bytes_total (Prometheus).

Додавання атрибутів `src.zone` та `dst.zone` до звичайних мережевих метрик

Атрибути зон доступності джерела та призначення стандартно вимкнені в OBI. Щоб увімкнути їх, явно додайте їх до списку включених мережевих атрибутів у YAML-конфігурації OBI:

Короткий опис стану специфікації

Thu, 26 Dec 2024 22:02:19 +0200

OpenTelemetry розробляється на основі сигналів. Трасування, метрики, baggage та логування є прикладами сигналів. Сигнали будуються на основі поширення контексту, спільного механізму для кореляції даних у розподілених системах.

Кожен сигнал складається з чотирьох основних компонентів:

Сигнали також мають додаткові компоненти, екосистему втулків та інструментів. Всі інструменти використовують однакові семантичні конвенції, щоб забезпечити однакові дані при спостереженні за загальними операціями, такими як HTTP-запити.

Щоб дізнатися більше про сигнали та компоненти, дивіться Огляд специфікації OTel.

OpenTelemetry

Prerequisites

Sign the CNCF CLA

Бібліотеки клієнтів Prometheus чи OpenTelemetry

Концептуальні відмінності

Розгортання OBI в Kubernetes

Налаштування декорування метаданих Kubernetes

Baggage

Приклад

Логи

Логи OpenTelemetry

Параметри конфігурації OBI Network Metrics

Міграція з OpenCensus

Запустіть OBI як контейнер Docker

Підписання та перевірка образів

Метрики

Глобальні властивості конфігурації OBI

Міграція з OpenTracing

Підтримка версій мов

Розгортання OBI в Kubernetes за допомогою Helm

Розгортання OBI з Helm

Швидкий старт з отримання мережевих метрик OBI

Розгортання OBI з мережевими метриками

Швидкий старт

Трейси

Налаштування режимів експорту OBI

Початок роботи

Налаштування

Декларативна конфігурація

Початок роботи

Вимірювання трафіку між зонами доступності хмари

Додавання атрибутів src.zone та dst.zone до звичайних мережевих метрик

Короткий опис стану специфікації

Додавання атрибутів `src.zone` та `dst.zone` до звичайних мережевих метрик