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

OpenTelemetry PHP Distro підтримує стандартну конфігурацію OpenTelemetry PHP SDK та специфічні для distro опції.

Метод конфігурації

Налаштуйте через змінні середовища, доступні для PHP-процесів:

• OTEL_* для стандартних опцій OpenTelemetry
• OTEL_PHP_* для специфічних для distro опцій

Приклад:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-endpoint:443/"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"
export OTEL_PHP_LOG_LEVEL_STDERR="INFO"

Опції OpenTelemetry

Distro підтримує стандартні опції OpenTelemetry PHP SDK.

Специфічні для Distro опції (OTEL_PHP_*)

Усі опції OTEL_PHP_* можна встановити як змінні середовища або в php.ini.

Для php.ini використовуйте префікс opentelemetry_distro. та імена опцій у нижньому регістрі.

Приклад:

export OTEL_PHP_ENABLED=true

opentelemetry_distro.enabled=true

Загальна конфігурація

Асинхронне надсилання даних

Логування

Відрізок транзакції

Інструментування на основі атрибутів

Міст залежностей з областями видимості

Виведені відрізки

Централізована конфігурація (OpAMP)

Можливість підтримки

Нотатки

• Фонова передача працює з режимом OTLP HTTP/protobuf.
• OTEL_PHP_AUTOLOAD_ENABLED примусово увімкнено distro runtime.
• Пакунок distro включає множинні залежності (OpenTelemetry SDK, різні автоінструментаційні пакунки та їх транзитивні залежності). Щоб уникнути конфліктів простору імен з власними залежностями застосунку, distro зазвичай використовує scoped (namespace-prefixed) залежності. Щоб повернутися до unscoped залежностей, встановіть OTEL_PHP_SCOPED_DEPS_ENABLED=false.

Залежності з обмеженим обсягом взаємодії

Стандартно OpenTelemetry runtime distro є scoped: його класи живуть під унікальним префіксом простору імен, окремого від стандартних класів OpenTelemetry\*, які застосунок встановив би через Composer. Як результат, власне використання OpenTelemetry застосунком виконується для окремого runtime і його відрізки а ні експортуються, а ні підключені до трейсів distro.

Встановлення OTEL_PHP_SCOPED_DEPS_BRIDGE_ENABLED=true створює міст між двома: до того, як автозавантажувач Composer застосунку запуститься, distro реєструє псевдоніми класів, що зіставляють unscoped OpenTelemetry\* API зі своєю scoped реалізацією. Власне використання OpenTelemetry додатком тоді прозоро використовує tracer provider та контекст distro, тому його відрізки експортуються та коректно батьківські в межах трейсів distro.

Ця опція не має ефекту, коли scoping вимкнено (OTEL_PHP_SCOPED_DEPS_ENABLED=false): без scoping distro вже використовує unscoped OpenTelemetry\* класи, тому спільне використання відбувається без якогось мосту.

Файлова конфігурація (декларативна)

Як альтернативу змінним середовища, ви можете налаштувати SDK, використовуючи YAML файл конфігурації, встановивши змінну середовища OTEL_CONFIG_FILE:

export OTEL_CONFIG_FILE=/path/to/otel-config.yaml

Коли OTEL_CONFIG_FILE встановлено:

• SDK читає всю конфігурацію з YAML файлу замість окремих змінних середовища OTEL_*.
• Підставлення змінних середовища (${MY_VAR:-default}) підтримується всередині YAML файлу.
• Централізована конфігурація (OpAMP) автоматично вимкнена — конфігурація на основі файлів та віддалена конфігурація є взаємовиключними.
• Специфічні для distro опції (OTEL_PHP_*) продовжують працювати, оскільки вони є нативними опціями розширення, незалежними від SDK.

Distro ресурс-детектор

Distro надає distro ресурс-детектор, що додає telemetry.distro.name та telemetry.distro.version атрибути ресурсу. Щоб активувати його у файловій конфігурації, додайте його до секції resource.detection/development.detectors:

file_format: '1.0-rc.2'

resource:
  attributes:
    - name: service.name
      value: my-service
  detection/development:
    detectors:
      - distro: {}

propagator:
  composite:
    - tracecontext:
    - baggage:

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/traces

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/metrics

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: http://localhost:4318/v1/logs

Для повної YAML схеми див. OpenTelemetry Configuration Schema.

Обмеження

• Центральна конфігурація (OpAMP) недоступна, якщо активна конфігурація на основі файлів.
• Ресурс-детектори, зареєстровані через Registry::registerResourceDetector() (наприклад, хмарні провайдери детекторів з opentelemetry-php-contrib) не активуються автоматично. Вони мають надавати ComponentProvider і бути явно перелічені у секції YAML resource.detection/development.detectors.