Внутрішня телеметрія

Ви можете перевірити стан будь-якого екземпляра OpenTelemetry Collector за допомогою його внутрішньої телеметрії. Читайте далі, щоб дізнатися про цю телеметрію та як її налаштувати, щоб допомогти вам моніторити та усувати несправності Колектора.

Активація внутрішньої телеметрії у колекторі

Стандартно колектор показує власну телеметрію двома способами:

• Внутрішні метрики експонуються за допомогою інтерфейсу Prometheus, який стандартно налаштовано на порт 8888.
• Журнали стандартно виводяться на stderr.

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

Колектор автоматично додає атрибути ресурсів service.name, service.version та service.instance.id (генеруються випадковим чином) до своїх внутрішніх телеметричних сигналів. Їх можна вимкнути, встановивши значення атрибуту null (наприклад, service.name: null).

Якщо ви хочете додати додаткові атрибути ресурсу до внутрішніх телеметричних сигналів колектора (трейси, метрики та журнали), ви можете встановити їх у service::telemetry::resource:

service:
  telemetry:
    resource:
      attribute_key: 'attribute_value'

Налаштування внутрішніх метрик

Експортер OTLP для внутрішніх метрик

Ви можете налаштувати, як колектор генерує та експонує внутрішні метрики. Стандартно, Колектор генерує основні метрики про себе і експонує їх за допомогою OpenTelemetry Go Prometheus exporter для отримання даних за адресою http://127.0.0.1:8888/metrics.

Колектор може передавати свої внутрішні метрики до бекенду OTLP за допомогою наступної конфігурації:

service:
  telemetry:
    metrics:
      readers:
        - periodic:
            exporter:
              otlp:
                protocol: http/protobuf
                endpoint: https://backend:4318

Точка доступу Prometheus для внутрішніх метрик

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

Налаштуйте конфігурацію Prometheus у розділі service::telemetry::metrics:

service:
  telemetry:
    metrics:
      readers:
        - pull:
            exporter:
              prometheus:
                host: '0.0.0.0'
                port: 8888

Якщо ви хочете додати додаткові мітки до метрик Prometheus, ви можете додати їх за допомогою prometheus::with_resource_constant_labels:

prometheus:
  host: '0.0.0.0'
  port: 8888
  with_resource_constant_labels:
    included:
      - label_key

А потім зробіть посилання на мітки в service::telemetry::resource:

resource:
  label_key: label_value

Адреса Service

service:
  telemetry:
    metrics:
      address: 0.0.0.0:8888

Рівень деталізації метрик

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

• none: телеметрія не збирається.
• basic: телеметрія основних сервісів.
• normal: стандартний рівень, додає стандартні показники на додачу до базових.
• detailed: найбільш докладний рівень, включає виміри та подання.

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

Стандартний рівень виведення метрик — normal. Щоб використовувати інший рівень, задайте service::telemetry::metrics::level:

service:
  telemetry:
    metrics:
      level: detailed

Перегляд метрик

Ви можете додатково налаштувати виведення метрик з колектора за допомогою views. Наприклад, у наведених нижче налаштуваннях метрику з назвою otelcol_process_uptime буде оновлено на нову назву process_uptime та опис:

service:
  telemetry:
    metrics:
      views:
        - selector:
            instrument_name: otelcol_process_uptime
            instrument_type:
          stream:
            name: process_uptime
            description: The amount of time the Collector has been up

Ви також можете використовувати views для оновлення кінцевої агрегації, атрибутів та лімітів кардинальності. Для повного списку опцій дивіться приклади у схемі конфігурації OpenTelemetry репозиторій.

Налаштування внутрішніх журналів

Вивід логів знаходиться у файлі stderr. Налаштувати логи можна у конфігураційному файлі service::telemetry::logs. Ось параметри конфігурації:

Ви також можете переглянути журнали колектора у системі Linux systemd за допомогою journalctl:

• Всі логи
• Тільки помилки

journalctl | grep otelcol

journalctl | grep otelcol | grep Error

Наступна конфігурація може бути використана для надсилання внутрішніх журналів з Колектора до OTLP/HTTP бекенда:

service:
  telemetry:
    logs:
      processors:
        - batch:
            exporter:
              otlp:
                protocol: http/protobuf
                endpoint: https://backend:4318

Налаштування внутрішніх трейсів

Стандартно колектор не показує трасування, але його можна налаштувати.

Наступна конфігурація може бути використана для надсилання внутрішніх трейсів з Колектора до бекенду OTLP:

service:
  telemetry:
    traces:
      processors:
        - batch:
            exporter:
              otlp:
                protocol: http/protobuf
                endpoint: https://backend:4318

Додаткові параметри наведено у example configuration. Зверніть увагу, що розділ tracer_provider там відповідає traces тут.

Типи внутрішньої телеметрії

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

Підсумок значень, спостережуваних за допомогою внутрішніх метрик

Колектор генерує внутрішні метрики щонайменше для таких значень:

• Час роботи процесу та час роботи CPU з моменту запуску.
• Використання памʼяті процесу та купи.
• Для приймачів: Прийняті та відхилені елементи для кожного типу даних.
• Для процесорів: Вхідні та вихідні елементи.
• Для експортерів: Елементи, які експортер надіслав, не поставив у чергу і не надіслав, за кожним типом даних.
• Для експортерів: Розмір і ємність черги.
• Кількість, тривалість і розмір HTTP/gRPC запитів і відповідей.

Більш детальний список доступний у наступних розділах.

Назви метрик

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

Префікс otelcol_

Починаючи з Collector v0.106.1, внутрішні назви метрик обробляються по-різному залежно від їхнього джерела:

• Метрики, створені з компонентів Колектора, мають префікс otelcol_.
• Метрики, створені з інструментальних бібліотек, стандартно не використовують префікс otelcol_, якщо тільки в їхніх назвах явно не вказано префікс.

У версіях Колектора до v0.106.1 всі внутрішні метрики, створені за допомогою експортера Prometheus, незалежно від їхнього походження, мають префікс otelcol_. Це включає метрики як з компонентів Колектора, так і з інструментальних бібліотек.

Суфікс _total

Стандартно і тільки для Prometheus, експортер Prometheus додає суфікс _total до сумарних метрик, щоб дотримуватися правил іменування Prometheus, наприклад otelcol_exporter_send_failed_spans_total. Цю поведінку можна вимкнути, встановивши without_type_suffix: false у конфігурації експортера Prometheus.

Якщо ви залишите service::telemetry::metrics::readers у конфігурації Collector, стандартний експортер Prometheus, налаштований Колектором, вже має without_type_suffix встановлений у false. Однак, якщо ви налаштуєте читачів і вручну додасте експортер Prometheus, ви повинні встановити цю опцію, щоб повернутися до “raw” імені метрики. Для отримання додаткової інформації див. Примітки до випуску Collector v1.25.0/v0.119.0.

Внутрішні метрики, що експонуються через OTLP, не мають цієї поведінки. Внутрішні метрики на цій сторінці наведені в OTLP форматі, такі як otelcol_exporter_send_failed_spans.

Крапки (.) чи підкреслення (_)

Метрики http* та rpc* походять з бібліотек інструментування. У їхніх оригінальних назвах використовувалися крапки (.). До версії Collector v0.120.0 внутрішні метрики, що експонувались за допомогою Prometheus, замінювали крапки (.) на підкреслення (_) відповідно до правил іменування Prometheus, в результаті чого назви метрик мали вигляд rpc_server_duration.

Версії 0.120.0 і пізніші колектора використовують сканери Prometheus 3.0, тому оригінальні назви метрик http* і rpc* з крапками зберігаються. Внутрішні метрики на цій сторінці наведені у своїй оригінальній формі, такі як rpc.server.duration. Для отримання додаткової інформації див. Примітки до випуску Collector v0.120.0.

Списки внутрішніх метрик

У наступних таблицях кожна внутрішня метрика згрупована за рівнем деталізації: basic, normal, та detailed. Кожна метрика ідентифікується за назвою та описом і класифікується за типом інструментарію.

Метрики рівня basic

Додаткові метрики рівня normal

Додаткові метрики рівня detailed

Події, які можна спостерігати у внутрішніх журналах

Колектор реєструє такі внутрішні події:

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

Рівні зрілості телеметрії

Рівні зрілості телеметрії Колектора застосовуються до всієї сторонньої телеметрії, створеної Колектором. Бібліотеки сторонніх розробників, у тому числі OpenTelemetry Go, не охоплюються цими рівнями зрілості.

Трасування

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

Метрики

Власні метрики Collector відповідають такому життєвому циклу:

stateDiagram-v2
    state StabilityLevels {
    InDevelopment --> Alpha
    Alpha --> Beta
    Beta --> Stable
    }

    InDevelopment: In Development

    StabilityLevels --> Deprecated
    Deprecated --> Removed

Рівні стабільності відповідають семантичним домовленостям, виведеним з OTEP-0232. Метрики колектора пропускають рівень release_candidate.

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

Сторонні метрики, включаючи ті, що генеруються інструментальними бібліотеками OpenTelemetry Go, не охоплюються цими рівнями зрілості.

Розробка

Показники розробки все ще знаходяться в стадії активної розробки і можуть змінюватися в будь-якій версії.

Альфа-метрика

Альфа-метрики не мають гарантій стабільності. Ці метрики можуть бути змінені або видалені в будь-який час.

Бета-метрика

Бета-метрики можуть змінюватися між релізами, але власники компонентів повинні намагатися мінімізувати руйнівні зміни. Цей етап сприяє ширшому використанню і є останнім кроком перед переходом до стадії stable.

Стабільна метрика

Стабільні метрики гарантовано не змінюватимуться. Це означає:

• Стабільна метрика без статусу застарілої не буде видалена або перейменована.
• Тип та атрибути стабільної метрики не будуть змінені.

Застаріла метрика

Застарілі метрики планується видалити, але вони все ще доступні для використання. Опис цих метрик включає анотацію про версію, в якій вони стали застарілими. Наприклад:

Перед застаріванням:

# HELP otelcol_exporter_queue_size це рахує щось
# TYPE otelcol_exporter_queue_size лічильник
otelcol_exporter_queue_size 0

Після застарівання:

# HELP otelcol_exporter_queue_size (Застаріла з 1.15.0) це рахує щось
# TYPE otelcol_exporter_queue_size лічильник
otelcol_exporter_queue_size 0

Видалена метрика

Видалені метрики більше не публікуються і не можуть бути використані.

Журнали

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

Використання внутрішньої телеметрії для моніторингу колектора

У цьому розділі наведено найкращі практики моніторингу колектора за допомогою його власної телеметрії.

Моніторинг

Довжина черги

Більшість експортерів надають механізм черги та/або повторної спроби, який рекомендується використовувати у будь-якому промисловому розгортанні Колектора.

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

За допомогою наступних трьох метрик ви можете визначити кількість відрізків, точок метрики і записів журналу, які не потрапили до черги надсилання:

• `otelcol_exporter_enqueue_failed_spans
• `otelcol_exporter_enqueue_failed_metric_points
• `otelcol_exporter_enqueue_failed_log_records

Ці помилки можуть бути спричинені переповненням черги невстановленими елементами. Можливо, вам слід зменшити швидкість надсилання або горизонтально масштабувати колектори.

Механізм черги або повторної спроби також підтримує ведення журналу для моніторингу. Перевірте журнали на наявність таких повідомлень, як Dropping data because sending_queue is full.

Помилки отримання

Сталі значення otelcol_receiver_refused_log_records, otelcol_receiver_refused_spans і otelcol_receiver_refused_metric_points вказують на те, що клієнтам було повернуто занадто багато помилок. Залежно від розгортання та відмовостійкості клієнтів, це може свідчити про втрату даних клієнтами.

Сталі показники otelcol_exporter_send_failed_log_records, otelcol_exporter_send_failed_spans і otelcol_exporter_send_failed_metric_points вказують на те, що колектор не може експортувати дані належним чином. Ці метрики за своєю суттю не означають втрату даних, оскільки можуть бути повторні спроби. Але висока кількість невдалих спроб може вказувати на проблеми з мережею або бекендом, який отримує дані.

Потік даних

Ви можете відстежувати надходження даних за допомогою метрик otelcol_receiver_accepted_log_records, otelcol_receiver_accepted_spans і otelcol_receiver_accepted_metric_points та вихід даних за допомогою метрик otelcol_exporter_sent_log_records, otelcol_exporter_sent_spans і otelcol_exporter_sent_metric_points.