Подорож до декларативної конфігурації: чому знадобилося 5 років, щоб ігнорувати точки доступу перевірки стану в трасуванні

Автор Gregor Zeitlinger(Grafana Labs), Jay DeLuca (Grafana Labs), Marylia Gutierrez (Grafana Labs) | Monday, October 20, 2025

Однією з найпоширеніших і найпопулярніших функцій, яку користувачі Java OpenTelemetry просили додати протягом останніх кількох років, була можливість ефективно видаляти відрізки для точок доступу контролю працездатності — або будь-які інші точки доступу з низькою цінністю, що збільшують витрати. Ця проблема була вперше піднята в серпні 2020 року, проте комплексне рішення залишалося недосяжним протягом напрочуд довгого часу. Чому нам знадобилося пʼять років, щоб вирішити цю, здавалося б, просту проблему? Відповідь лежить у фундаментальних принципах системи конфігурації OpenTelemetry та у переході до більш надійного та гнучкого підходу: декларативної конфігурації.

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

Зʼявилася декларативна конфігурація — потужна еволюція, яка використовує файли YAML для визначення налаштувань OpenTelemetry. Ця зміна дозволяє читати дані з будь-якого джерела у вигляді дерева, що кардинально змінює наш підхід до складних конфігурацій. У цій публікації ми розглянемо, як декларативна конфігурація забезпечує елегантне рішення проблем минулого, і продемонструємо її безпосередній вплив на практичному прикладі. cases like health check exclusion in Java.

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

Файл конфігурації не залежить від мови, тому, створивши один файл, ви можете використовувати його для всіх своїх SDK. Єдиними винятками є параметри з конкретною назвою мови, які стосуються лише цієї мови (наприклад, параметр instrumentation/development.java.spring_batch). Майте на увазі, що декларативна конфігурація є експериментальною, тому вона може змінюватися.

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

file_format: '1.0-rc.1'

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
  detection/development:
    detectors:
      - service: # додасть "service.instance.id" та "service.name" з OTEL_SERVICE_NAME

propagator:
  composite:
    - tracecontext:
    - baggage:

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:-http://localhost:4318/v1/traces}

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_METRICS_ENDPOINT:-http://localhost:4318/v1/metrics}

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_LOGS_ENDPOINT:-http://localhost:4318/v1/logs}

Все, що вам потрібно зробити, це передати OTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/otel-config.yaml до застосунку, щоб активувати експериментальну опцію декларативної конфігурації. На момент написання ця змінна працює тільки в Java-агенті та JavaScript.

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

Тепер розглянемо більш широке впровадження декларативної конфігурації в екосистемі Java. Як піонер у цій галузі, Java-агент 2.21+ тепер повністю підтримує декларативну конфігурацію, більшість інструментацій та функцій вже функціонують. Ми працюємо над впровадженням решти функцій протягом 2026 року, і ви можете відстежувати наш прогрес на дошці проєкту і переглядати список функцій, які ще не підтримуються.

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

Приклад базового (незалежного від мови) файлу конфігурації з попереднього розділу є найшвидшим способом почати, коли вам не потрібно жодних подальших налаштувань.
Файл конфігурації міграції переносить старі змінні середовища в YAML-схему, що дозволяє замінити їх для користувачів, які вже налаштували робочі навантаження за допомогою змінних середовища.
Повний файл конфігурації (“kitchen sink”) показує всю схему, прокоментовану документацією. Це корисно для користувачів, які хочуть бачити всі доступні параметри та їх стандартні значення.

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

Крім того, існує багато налаштувань, специфічних для Java-агента, які входять до секції інструментації вашого файлу конфігурації. Наприклад, якщо у вас є системна змінна otel.instrumentation.spring-batch.experimental.chunk.new-trace у вашому застосунку, ви можете створити файл декларативної конфігурації, видаливши префікс otel.instrumentation, розділивши на . і перетворивши - на _.

file_format: '1.0-rc.1'

# ...

instrumentation/development:
  java:
    spring_batch:
      experimental:
        chunk:
          new_trace: true

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

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

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

Щоб досягти цього, вам потрібно додати новий блок sampler у вашу конфігурацію tracer_provider, як показано нижче:

file_format: '1.0-rc.1'

# ... решта конфігурації ....

tracer_provider:
  # Налаштуйте вибірку, щоб виключити точки доступу контролю працездатності.
  sampler:
    rule_based_routing:
      fallback_sampler:
        always_on:
      span_kind: SERVER
      rules:
        # Дія, яку слід виконати, коли правило виконується. Повинно бути DROP або RECORD_AND_SAMPLE.
        - action: DROP
          # Атрибут відрізка, з яким слід порівняти.
          attribute: url.path
          # Шаблон для порівняння з атрибутом відрізка.
          pattern: /actuator.*
# ... решта конфігурації tracer_provider ...

Більш детальну інформацію про доступні опції дивіться в документації Java Sampler.

Спробуйте самі:

Збережіть повну конфігурацію
Запустіть Java-агент з -Dotel.experimental.config.file=/path/to/otel-config.yaml

Доступність

Після ознайомлення з декларативною конфігурацією, ви, можливо, запитаєте, де вона доступна і як ви можете почати її використовувати. Ви можете знайти вказівки щодо початку роботи та підтримуваних мов у документації. На момент написання цього поста Java повністю відповідає вимогам, а PHP, JavaScript і Go частково відповідають. Щоб побачити останній статус, перевірте матрицю відповідності або тікет, що відстежує реалізації мов.

Java

Як вже згадувалося раніше, декларативна конфігурація в Java є експериментальною, але готовою до використання. Використовуйте приклад, про який ми говорили раніше, щоб налаштувати вашу нову конфігурацію. Якщо у вас є питання або відгуки, звертайтеся в #otel-java на CNCF Slack.

Примітка для розробників для інших мов: корисно створити модуль-міст, який адаптує декларативні налаштування конфігурації та змінні середовища до загального інтерфейсу. Для Java це Declarative Config Bridge.

JavaScript

Реалізація в SDK JavaScript наразі створюється. Було створено новий пакет з назвою opentelemetry-configuration, який обробляє як змінні середовища, так і декларативну конфігурацію. Завдяки цьому підходу користувачеві не потрібно змінювати свою інструментацію, коли він переходить між змінними середовища та конфігураційним файлом, оскільки новий пакет обробляє це і повертає одну й ту ж модель конфігурації для обох випадків. Наразі цей конфігураційний пакет додається до інших пакетів інструментації, щоб вони могли скористатися декларативною конфігурацією. Якщо у вас є питання, звертайтеся в #otel-js на CNCF Slack.

PHP

Реалізація в PHP частково відповідає вимогам, і ви можете почати використовувати її, ініціалізувавши з вашого файлу конфігурації. Для отримання допомоги або зворотного звʼязку звертайтеся в #otel-php на CNCF Slack.

Go

Go має часткову реалізацію декларативної конфігурації. Кожна підтримувана версія схеми має свій відповідний каталог пакунків. Наприклад, імпортуючи go.opentelemetry.io/contrib/otelconf/v0.3.0, ви отримуєте код, який підтримує версію 0.3.0 схеми конфігурації. Ви можете знайти всі доступні версії в індексі пакунків. Якщо у вас є питання щодо використання, звертайтеся в #otel-go на CNCF Slack.

Подорож

То чому ж насправді нам знадобилося пʼять років, щоб ігнорувати точки доступу перевірки стану в трасуванні?

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

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

Заміною, як ми представили в цьому блозі, є декларативна конфігурація. Створення та узгодження точного синтаксису та семантики було трудомістким і, часом, виснажливим процесом. Наприклад, ми розглянули кілька пропозицій щодо того, як можна вбудувати змінні середовища, поки не дійшли до поточного рішення використовувати ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}.

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

Що далі для декларативної конфігурації?

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

Ми з нетерпінням чекаємо на відгуки від користувачів, оскільки продовжуємо розвивати та вдосконалювати ці функції. Ми закликаємо вас почати експериментувати з поточними реалізаціями та активно повідомляти про будь-які відсутні функціональні можливості, проблеми або сфери для вдосконалення. Цей колективний підхід допоможе нам встановити пріоритети для розробки та забезпечити, щоб рішення, які ми створюємо, дійсно відповідали потребам спільноти. Ви можете поділитися своїми відгуками або запитаннями, використовуючи канал #otel-config-file на CNCF Slack.

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

Ми сподіваємося на ваші відгуки!

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

Щоб дізнатися більше про роботу, що проводиться для декларативної конфігурації, ось кілька додаткових ресурсів для ознайомлення:

Востаннє змінено October 20, 2025: [uk] Blog Declarative config (1d1ae8d4)