Экспортёр CDI OpenTelemetry не включён по умолчанию в Quarkus v3.27.0

Содержание

• Понимание утверждения в документации
• Опыт пользователей против документации
• Возможные объяснения расхождения
• Правильные подходы к конфигурации
• Альтернативные варианты экспортера
• Проверка и отладка
• Рекомендации

Понимание утверждения в документации

Согласно официальной документации Quarkus OpenTelemetry, активный экспортер автоматически настраивается через CDI, поэтому свойства quarkus.otel.traces.exporter, quarkus.otel.metrics.exporter и quarkus.otel.logs.exporter имеют значение по умолчанию ‘cdi’. Это означает, что при включении OpenTelemetry в приложении Quarkus он должен автоматически настраивать экспортер CDI без необходимости явной конфигурации.

В документации указано, что этот экспортер CDI построен на основе Vert.x для оптимальной производительности и поддерживаемости, а все встроенные экспортеры Quarkus используют протокол OTLP через отправщики данных, где gRPC является значением по умолчанию, а http/protobuf — альтернативой.

Однако заявленное поведение по умолчанию, похоже, не соответствует реальному опыту пользователей на практике.

Опыт пользователей против документации

Ваше наблюдение, что ни один экспортер не настроен для трейсов, когда вы явно не устанавливаете quarkus.otel.traces.exporter=cdi, подтверждается несколькими отчетами пользователей:

• В обсуждении GitHub #34964 пользователь сообщает: “При предложенной конфигурации я вообще не получал спанов в jaeger. Думаю, это потому, что значение по умолчанию для quarkus.otel.traces.exporter равно cdi, и его нужно было установить в otlp.”

• Это указывает на то, что хотя документация и утверждает ‘cdi’ как значение по умолчанию, пользователи обнаруживают, что трейсы на самом деле не экспортируются без явной конфигурации.

Расхождение становится более очевидным, когда вы учитываете, что:

1. Документация утверждает об автоматической настройке через CDI
2. Опыт пользователей показывает отсутствие экспорта трейсов без явной конфигурации
3. Отладка io.opentelemetry.sdk.autoconfigure.TracerProviderConfiguration.configureBatchSpanProcessor() подтверждает отсутствие активного экспортера

Это несоответствие между документацией и фактическим поведением создает путаницу у разработчиков, следующих официальным руководствам.

Возможные объяснения расхождения

Несколько факторов могут объяснить, почему задокументированное поведение по умолчанию не работает как ожидается:

1. Проблемы с зависимостями расширения

Функциональность OpenTelemetry может работать правильно только при явном добавлении расширения Quarkus OpenTelemetry в проект. Как отмечено в обсуждении #31635, “Конфигурация применяется только при добавлении расширения Quarkus OpenTelemetry в проект Quarkus.”

2. Ограничения автоматической настройки

Автоматическая настройка может иметь условия, которые не выполняются в вашей настройке. Экспортеру CDI могут потребоваться определенные зависимости или конфигурации, которые не удовлетворяются автоматически.

3. Поведение, специфичное для версии

Хотя вы используете v3.27.0, могут существовать нюансы или ошибки, специфичные для версии, влияющие на поведение по умолчанию. Документация может отражать предполагаемое поведение, а не фактическую реализацию.

4. Условное активация

Экспортер CDI может активироваться только при определенных условиях (например, конкретные профили, зависимости или комбинации конфигураций), которые не задокументированы или не очевидны.

5. Проблемы с приоритетом конфигурации

Могут существовать проблемы с приоритетом конфигурации, когда другие настройки переопределяют значение экспортера по умолчанию ‘cdi’.

Правильные подходы к конфигурации

Учитывая расхождение между документацией и фактическим поведением, вот рекомендуемые подходы к правильной настройке трассировки OpenTelemetry в Quarkus:

Явная конфигурация экспортера CDI

# Явно включить экспортер CDI для трейсов
quarkus.otel.traces.exporter=cdi

# Настроить OTLP конечную точку для экспортера CDI
quarkus.otel.exporter.otlp.endpoint=http://localhost:4317
quarkus.otel.exporter.otlp.compression=none

Пример полной конфигурации

На основе обсуждения #44956, вот более комплексная конфигурация:

# Включить OpenTelemetry
quarkus.otel.enabled=true

# Настроить экспортер трейсов
quarkus.otel.traces.exporter=cdi
quarkus.otel.exporter.otlp.endpoint=http://localhost:4317
quarkus.otel.exporter.otlp.compression=none

# Настроить параметры пакетного процессора
quarkus.otel.bsp.export.timeout=10S
quarkus.otel.bsp.max.export.batch.size=512
quarkus.otel.bsp.schedule.delay=5S

# Настроить атрибуты ресурса
quarkus.otel.resource.attributes=service.name=my-service,service.namespace=production

Конфигурация CDI Bean

Вам также может потребоваться убедиться, что у вас правильно настроены CDI beans. Расширение OpenTelemetry должно автоматически обнаруживать и настраивать Resource CDI beans, объединяя их при настройке OTel SDK.

Альтернативные варианты экспортера

Если экспортер CDI работает не как ожидается, вы можете рассмотреть альтернативные подходы:

Прямая конфигурация экспортера OTLP

# Использовать экспортер OTLP напрямую
quarkus.otel.traces.exporter=otlp
quarkus.otel.exporter.otlp.endpoint=http://localhost:4317

Расширения экспортера Quarkiverse

Проект Quarkiverse quarkus-opentelemetry-exporter предоставляет дополнительные экспортеры помимо тех, что включены по умолчанию в Quarkus.

Экспортеры, специфичные для платформы

Для конкретных платформ, таких как Google Cloud, можно использовать:

quarkus.opentelemetry.tracer.exporter.gcp.enabled=true

Проверка и отладка

Для проверки конфигурации OpenTelemetry и отладки проблем:

Отладка процесса конфигурации

Как вы упоминали, отладка метода io.opentelemetry.sdk.autoconfigure.TracerProviderConfiguration.configureBatchSpanProcessor() может помочь подтвердить, действительно ли экспортер настраивается.

Проверка логов запуска приложения

Ищите сообщения, связанные с OpenTelemetry, во время запуска приложения, которые указывают на инициализацию или настройку экспортеров.

Проверка подключения к коллектору

Убедитесь, что ваш OpenTelemetry коллектор запущен и доступен по настроенной конечной точке. Вы можете проверить подключение с помощью:

curl http://localhost:4317

Использование режима разработки Quarkus

Запустите ваше приложение в режиме разработки (./mvnw quarkus:dev), чтобы увидеть более подробную информацию о конфигурации и запуске.

Рекомендации

На основе результатов исследования и вашего опыта:

1. Всегда явно настраивайте экспортер: Не полагайтесь на задокументированное поведение по умолчанию. Явно установите quarkus.otel.traces.exporter=cdi в вашей конфигурации.

2. Проверьте зависимости расширения: Убедитесь, что расширение Quarkus OpenTelemetry правильно включено в зависимости вашего проекта.

3. Проверьте профили конфигурации: Убедитесь, что ваша конфигурация применяется в правильном профиле (dev, test, prod).

4. Мониторьте логи запуска: Обращайте внимание на сообщения, связанные с OpenTelemetry, во время запуска приложения для выявления проблем с конфигурацией.

5. Рассмотрите прямой использование OTLP: Если экспортер CDI продолжает вызывать проблемы, рассмотрите возможность использования экспортера OTLP напрямую с явной конфигурацией.

6. Сообщите о расхождении: Рассмотрите возможность сообщения об этом расхождении в документации команде Quarkus, чтобы они могли прояснить фактическое поведение и, возможно, исправить реализацию или документацию.

Разрыв между задокументированным поведением по умолчанию и фактической реализацией создает ненужную путаницу для разработчиков. Явная настройка экспортера CDI позволит обеспечить правильный экспорт трейсов, несмотря на расхождение в документации.

Источники

1. Использование OpenTelemetry - Документация Quarkus
2. Пропущенные элементы конфигурации в руководстве по использованию Opentelemetry - Обсуждение GitHub
3. Ошибка зависимости запуска экспортера OpenTelemetry - Проблема GitHub
4. Почему OpenTelemetry включен по умолчанию - Обсуждение GitHub
5. Включить использование других SpanExporters - Проблема GitHub
6. Интеграция Apache Camel с OpenTelemetry
7. Использовать http экспортер OpenTelemetry - Обсуждение GitHub
8. Как настроить OpenTelemetry - Обсуждение GitHub
9. Документация экспортера Quarkus OpenTelemetry
10. Quarkus OpenTelemetry и локальный агент - Stack Overflow