Настройка Service Structure в Tempo для корректной работы

Для корректной работы Service Structure в Tempo необходимо настроить несколько ключевых компонентов. Ваша конфигурация в целом верна, но есть несколько важных моментов, которые могут вызывать проблемы.

Содержание

• Основные проблемы с Service Structure
• Конфигурация Tempo для Service Graphs
• Настройка OpenTelemetry для корректных меток
• Проверка и отладка Service Graphs
• Настройка Grafana для отображения Service Structure

Основные проблемы с Service Structure

Service Structure в Tempo не работает обычно из-за одной из следующих причин:

1. Отсутствие правильных меток service.name в трейсах
2. Неполная конфигурация процессоров в Tempo
3. Недостаточное время для генерации service graph данных
4. Неправильная настройка Grafana для отображения service graphs

Ваша текущая конфигурация выглядит почти правильно, но требует некоторых доработок.

Конфигурация Tempo для Service Graphs

Ваш tempo.yaml нуждается в следующих изменениях:

server:
  http_listen_port: 3200

distributor:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: "0.0.0.0:4317"
        http:
          endpoint: "0.0.0.0:4318"  # Добавлен HTTP receiver
  log_received_spans:
    enabled: true

compactor:
  compaction:
    block_retention: 48h

metrics_generator:
  registry:
    external_labels:
      source: tempo
      cluster: docker-compose
  
  storage:
    path: /var/tempo/wal
    remote_write:
      - url: http://prometheus:9090/api/v1/write
        send_exemplars: true
  traces_storage:
    path: /var/tempo/traces
  processor:
    service-graphs:
      # Добавлена специфичная конфигурация для service graphs
      lookback: 30m
      sampling_ratio: 1.0
    local_blocks:
      filter_server_spans: false
      flush_to_storage: true

storage:
  trace:
    backend: local
    local:
      path: /var/tempo/traces
    wal:
      path: /var/tempo/wal

overrides:
  defaults:
    cost_attribution:
      dimensions:
        service.name: ""
        span.http.target: "service_route"
    metrics_generator:
      processors: [service-graphs, span-metrics, local-blocks]
      generate_native_histograms: both

Ключевые изменения:

• Добавлен HTTP receiver для большей совместимости
• Добавлена специфичная конфигурация для service-graphs processor
• Увеличен lookback период для лучшего охвата данных

Настройка OpenTelemetry для корректных меток

Самая частая причина неработающей Service Structure — отсутствие правильных меток service.name. Убедитесь, что ваш OpenTelemetry конфигурация правильно устанавливает эту метку.

Пример правильной настройки для Nuxt + Pino:

// В вашем OpenTelemetry конфиге
export default defineNuxtPlugin(() => {
  const otelConfig = {
    serviceName: 'ваше-приложение', // Обязательно уникальное имя
    instrumentations: [
      new ResourceAttributesInstrumentation({
        attributes: {
          'service.name': 'ваше-приложение',
          'service.version': '1.0.0',
        }
      })
    ]
  }
  
  // ... остальная конфигурация
})

Важно: Каждая микросервисная часть вашего приложения должна иметь уникальное service.name. Если несколько сервисов используют одно и то же имя, Tempo не сможет правильно построить service graph.

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

Чтобы убедиться, что Service Structure работает, выполните следующие шаги:

1. Проверьте presence меток:

   bash

   # Запросите трейсы с сервисными метками
   curl "http://localhost:3200/api/search?query=service.name"
   

2. Проверьте доступность service graph данных:

   bash

   # Проверьте наличие service graph метрик в Prometheus
   curl "http://localhost:9090/api/v1/label/__name__/values"
   # Ищите метрики с префиксом 'tempo_service_graph'
   

3. Проверьте логи Tempo:

   bash

   # В логах Tempo должны быть сообщения о генерации service graphs
   docker logs tempo | grep "service-graphs"
   

4. Дождитесь достаточного времени: Service graphs генерируются асинхронно и могут требовать 5-15 минут для появления после начала сбора трейсов.

Настройка Grafana для отображения Service Structure

В Grafana необходимо правильно настроить dashboard для отображения service graphs:

1. Добавьте Tempo datasource в Grafana

2. Используйте встроенный dashboard для service graphs:

   • ID: 16090 (Grafana Tempo Service Graph dashboard)
   • Или создайте свой с использованием следующих запросов:
   promql

   # Запрос для service graph
   tempo_service_graph_edges_total{service_name!="", job="tempo-usage-metrics"}
   
   # Запрос для вершин графа
   tempo_service_graph_nodes_total{service_name!="", job="tempo-usage-metrics"}
   

3. Настройте панель визуализации:

   • Используйте плагин Graph или Network Graph
   • Настройте правильные параметры отображения
   • Убедитесь, что время запроса охватывает период генерации service graphs (не менее 30 минут)

Если после всех этих настроек Service Structure все равно не работает, проверьте:

• Есть ли в трейсах метки service.name
• Все ли сервисы отправляют данные в Tempo
• Нет ли ошибок в логах Tempo и Prometheus
• Достаточно ли данных собрано для построения графа

Обычно проблема решается правильной настройкой service.name меток и ожиданием достаточного времени для генерации service graph данных.

Источники

1. Grafana Tempo Documentation - Service Graphs
2. OpenTelemetry Semantic Conventions - Service Name
3. Grafana Tempo Troubleshooting
4. Grafana Tempo Dashboards