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

Декларативна конфігурація використовує схему декларативної конфігурації OpenTelemetry всередині вашого application.yaml.

Цей підхід корисний, коли:

• У вас багато параметрів конфігурації для налаштування
• Ви хочете використовувати параметри конфігурації, які недоступні через application.properties або application.yaml
• Ви хочете використовувати той самий формат конфігурації, що й Java агент

Підтримувані версії

Декларативна конфігурація підтримується у OpenTelemetry Spring Boot starter версії 2.26.0 і пізніших.

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

Додайте otel.file_format: "1.0" (або поточну чи бажану версію) до вашого application.yaml, щоб увімкнути декларативну конфігурацію:

otel:
  file_format: '1.0'

  resource:
    detection/development:
      detectors:
        - service:
    attributes:
      - name: service.name
        value: my-spring-app

  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}

Зверніть увагу, що ${VAR:default} використовує двокрапку (синтаксис Spring), а не ${VAR:-default}, який використовується у YAML-файлі агента.

Перетворення наявної конфігурації

Зіставлення параметрів конфігурації

Наступні правила описують, як параметри конфігурації application.properties / application.yaml відповідають їх еквівалентам у декларативній конфігурації:

Увімкнення/вимкнення інструменталізації

У декларативній конфігурації увімкнення/вимкнення інструменталізації використовує централізовані списки замість окремих властивостей. Назва інструменталізації використовує _ (snake_case), а не - (kebab-case).

Приклад:

otel:
  distribution:
    spring_starter:
      instrumentation:
        default_enabled: false
        enabled:
          - jdbc
          - spring_web
        disabled:
          - logback_appender

Конфігурація інструменталізації

Параметри конфігурації під otel.instrumentation.* (крім увімкнення/вимкнення) відповідають otel.instrumentation/development.java.*:

1. Видаліть префікс otel.instrumentation.
2. Для кожного сегмента: замініть - на _
3. Розмістіть під otel.instrumentation/development.java.
4. Суфікс /development у ключі вказує на експериментальну функцію (див. метод translateName у ConfigPropertiesBackedDeclarativeConfigProperties для зворотного відображення)

Приклад:

Деякі параметри мають спеціальні відображення, які не відповідають стандартному алгоритму:

Розділ instrumentation/development має дві групи верхнього рівня:

• general.* — Крос-мовна конфігурація (HTTP заголовки, стабільність семантичних конвенцій)
• java.* — Конфігурація інструментування, специфічна для Java

Вимкнення SDK

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

Конфігурація на рівні SDK (експортери, пропагатори, ресурси) слідує стандартній схемі декларативної конфігурації безпосередньо під otel:, як показано в прикладі Початок роботи.

Відмінності від декларативної конфігурації агента

Перевизначення змінних середовища

Гнучка система привʼязки Spring дозволяє замінити будь-яку частину декларативної конфігурації YAML за допомогою змінних середовища:

# Перевизначення скалярного значення в instrumentation/development
OTEL_INSTRUMENTATION/DEVELOPMENT_JAVA_FOO_STRING_KEY=new_value

# Перевизначення елемента списку за індексом (наприклад, endpoint експортера)
OTEL_TRACER_PROVIDER_PROCESSORS_0_BATCH_EXPORTER_OTLP_HTTP_ENDPOINT=http://custom:4318/v1/traces

Правила: великі літери, заміна . на _, залишати / без змін (наприклад INSTRUMENTATION/DEVELOPMENT), використовувати _0_, _1_ для індексів списку.

Це стандартна функція Spring — вона працює для будь-якого ключа в application.yaml.

Формат тривалості

Декларативна конфігурація підтримує тривалості лише в мілісекундах (наприклад, 5000 для 5 секунд). Ви отримаєте помилку, якщо використаєте рядок тривалості, такий як 5s.

Програмна конфігурація

З декларативною конфігурацією, AutoConfigurationCustomizerProvider (див. Програмна конфігурація) замінюється на DeclarativeConfigurationCustomizerProvider. Компоненти, такі як експортера відрізків, використовують API ComponentProvider. Дивіться розділ Розширення API для Агента для деталей та прикладів — ті ж API застосовуються до Spring Boot starter.