Трассировка узлов и шардов в OpenSearch 3.1 для DBQ-запросов

В OpenSearch 3.1 трассировки на уровне узлов и шардов для DBQ-запросов часто не видны из-за конфликта с security plugin, который перехватывает заголовки, или неполной настройки OTEL-экспортера с endpoint Jaeger. Добавьте telemetry.otel.tracer.span.exporter.otlp.endpoint=http://jaeger-host:4317/v1/traces, используйте заголовок Trace: true в запросах вместо URL-параметра, перезапустите opensearch кластер — и детальные спаны node/shard появятся в Jaeger для анализа медленных opensearch query. Это активирует полную телеметрию, показывая фазы вроде indices:data/read/search[phase/query].

Содержание

• Почему не отображаются трассировки узлов и шардов в OpenSearch 3.1
• Основные настройки телеметрии для opensearch monitoring и Jaeger
• Устранение конфликтов с opensearch security plugin
• Настройка OpenTelemetry экспортера для opensearch query и DBQ
• Активация трассировки в запросах: заголовки и параметры
• Проверка и отладка в opensearch кластер с Docker
• Альтернативы: slow logs и opensearch dashboards для анализа производительности
• Источники
• Заключение

Почему не отображаются трассировки узлов и шардов в OpenSearch 3.1

Вы видите только HTTP-трассировки в Jaeger, а детальные спаны узлов и шардов для DBQ-запросов пропадают. Почему так? В OpenSearch 3.1 телеметрия — экспериментальная фича, и по умолчанию она не захватывает внутренние операции вроде фаз query или fetch на шардах. Ваши настройки (telemetry.feature.tracer.enabled=true, opensearch.experimental.feature.telemetry.enabled=true) верны, но без полного стека OTEL и правильного сэмплинга спаны node-level просто не генерируются или не экспортируются.

Представьте: запрос DBQ приходит по HTTP, tracer ловит внешний span, но внутри кластера security plugin (если включен) глотает trace-заголовки. Результат — пустые узлы в Jaeger. Плюс, в локальной установке с Docker часто забывают перезапуск после изменений в opensearch.yml. По данным официальной документации OpenSearch, это типичная засада для opensearch monitoring на версии 3.x.

А что с DBQ конкретно? Эти запросы распределяются по шардам, и без telemetry.tracer.sampler.probability=1 (полный сэмплинг) низковероятные спаны отсеиваются. Но даже с ним — ждите шард-спаны вроде query_phase только после фикса экспортера.

Основные настройки телеметрии для opensearch monitoring и Jaeger

Начните с базовой конфигурации в opensearch.yml на всех узлах. Вот полный набор для OpenSearch 3.1:

opensearch.experimental.feature.telemetry.enabled: true
telemetry.feature.tracer.enabled: true
telemetry.tracer.enabled: true
telemetry.tracer.sampler.probability: 1.0
plugins.telemetry_otel.enabled: true

Почему 1.0, а не 1? Это float, иначе сэмплер игнорирует. Добавьте батч-опции для производительности:

telemetry.otel.tracer.exporter.max_queue_size: 2048
telemetry.otel.tracer.exporter.max_export_batch_size: 512
telemetry.otel.tracer.exporter.export_timeout: 5000

После правок — полный перезапуск кластера. systemctl restart opensearch или docker-compose restart в локалке. Без этого изменения не подхватятся. В логах узлов ищите: [INFO ][o.o.t.Tracer] Tracer initialized — признак успеха.

Это базис для opensearch shard трассировки. Без него Jaeger получит только HTTP-оболочку, а не breakdown по фазам DBQ.

Устранение конфликтов с opensearch security plugin

Security plugin — главный виновник. Он перехватывает входящие запросы, стирая или переопределяя traceparent/traceId заголовки. В вашей локальной установке он, скорее всего, включен по умолчанию.

Решение от Deepti на Stack Overflow: отключите его временно для теста:

plugins.security.disabled: true

Или настройте пропуск trace-заголовков в security config (plugins/security/config.yml):

restapi:
 allowed_trace_headers: ["traceparent", "tracestate", "trace-id"]

Перезапустите. Теперь DBQ-запросы пройдут чистыми, и узловые спаны потекут в Jaeger. Но в проде не глушите security полностью — лучше whitelist’ьте headers в action-groups.

Тестировал сам? В Docker-compose.yml добавьте env: DISABLE_SECURITY_PLUGIN=true. Узлы начнут генерировать спаны вроде node_coordinating_only и shard_fetch.

Настройка OpenTelemetry экспортера для opensearch query и DBQ

Ваш telemetry.otel.tracer.span.exporter.class обрезан — должно быть io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter. Полная секция:

telemetry.otel.tracer.span.exporter.class: io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter
telemetry.otel.tracer.span.exporter.otlp.endpoint: http://localhost:4318/v1/traces # Jaeger all-in-one:4318 или collector:4317
telemetry.otel.tracer.span.exporter.otlp.headers: {"Authorization": "Bearer your-token-if-needed"}

Jaeger в Docker? Убедитесь, что порт 4317/4318 открыт и OTLP включен. В jaeger.yml:

protocol: otlp
endpoint: 0.0.0.0:4317

Почему endpoint важен? Без /v1/traces спаны не парсятся. Документация OpenSearch подчеркивает: для Jaeger используйте HTTP OTLP, не GRPC по умолчанию.

Для DBQ добавьте telemetry.tracer.internal.spans.enabled: true — это вытащит query/parser/fetch спаны по шардам.

Активация трассировки в запросах: заголовки и параметры

Не полагайтесь на ?trace=true — это устарело. Используйте HTTP-заголовок Trace: true в curl или клиенте:

curl -H "Trace: true" -H "traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01" "localhost:9200/myindex/_dbquery"

Формат traceparent: version-traceId-parentId-flags. Генерируйте в клиенте (Postman или коде). Форум OpenSearch советует: это активирует full-span для opensearch запросы, включая DBQ.

В opensearch dashboards? В Dev Tools добавьте заголовок вручную. Без него sampler игнорирует низкопроизводительные запросы.

Тест: отправьте DBQ, чекните Jaeger — увидите tree с search_query, rewrite, shard подузлами.

Проверка и отладка в opensearch кластер с Docker

Локалка на Docker? Docker-compose с OpenSearch 3.1 + Jaeger:

version: '3'
services:
 opensearch:
 image: opensearchproject/opensearch:3.1.0
 environment:
 - discovery.type=single-node
 - plugins.security.disabled=true
 - "OPENSEARCH_JAVA_OPTS=-Dopensearch.experimental.feature.telemetry.enabled=true -Dtelemetry.feature.tracer.enabled=true ..."
 ports: - 9200:9200
 jaeger:
 image: jaegertracing/all-in-one:1.57
 ports: - 16686:16686 - 4317:4317

Запустите docker-compose up -d, настройте endpoint на http://jaeger:4317. Логи: docker logs opensearch — ищите tracer spans.

В Jaeger UI (localhost:16686) фильтр по service=opensearch, operation=search. Нет спанов? Увеличьте логи: logger.org.opensearch.telemetry.level: DEBUG.

Для кластера: реплицируйте на multi-node, чекните cross-node spans.

Альтернативы: slow logs и opensearch dashboards для анализа производительности

Трассировка не взлетела? Вкрутите slow logs:

index.search.slowlog.threshold.query.warn: 10s
index.search.slowlog.threshold.fetch.debug: 500ms

Логи покажут breakdown по шардам без Jaeger. В opensearch dashboards — профайлер запросов: Analyze → Profiler, там DBQ timings.

Grafana с Prometheus? Плагин opensearch exporter для метрик shard/query latency. Быстрее телеметрии для dev.

Но трассировка — топ для корреляции, так что фиксите её первой.

Источники

1. Distributed Tracing — Настройки телеметрии, OTEL-экспортера и активации спанов в OpenSearch: https://docs.opensearch.org/latest/observing-your-data/trace/distributed-tracing/
2. OpenSearch 3.1 not showing traces at node level for DBQ query — Обсуждение конфликта security plugin с trace-заголовками: https://stackoverflow.com/questions/79880131/open-search-3-1-not-showing-traces-at-node-level-for-dbq-query
3. Enable telemetry OTEL for OpenSearch 2.12 — Рекомендации по заголовкам Trace и экспортеру для Jaeger: https://forum.opensearch.org/t/enable-telemetry-otel-for-opensearch-2-12/18789

Заключение

Настройка трассировки узлов и шардов в OpenSearch 3.1 сводится к полному OTEL-стеку, фиксу security, заголовку Trace: true и перезапуску — тогда Jaeger покажет полный breakdown DBQ для opensearch query. Не забудьте сэмплинг 1.0 и endpoint /v1/traces. Если не сработает, slow logs спасут. В итоге, вы получите мощный инструмент для opensearch monitoring, сэкономив часы на слепой отладке. Тестируйте поэтапно — и производительность взлетит.