Index

Централизованная система распределенной трасировки с использованием OpenTelemetry Collector и Grafana Tempo.

Оглавление

Описание

OpenTelemetry Collector - централизованный шлюз для сбора, обработки и экспорта телеметрии (трейсы, метрики, логи).

Tempo - высокопроизводительная система хранения распределенных трейсов от Grafana, использующая S3-совместимое хранилище.

Tempo Operator - Kubernetes оператор для управления Tempo через декларативные CR (Custom Resources).

Возможности

  • ✅ Централизованный сбор трейсов через OTLP (gRPC/HTTP)
  • ✅ Хранение трейсов в MinIO S3 (30 дней retention)
  • ✅ Генерация метрик из трейсов (RED: Rate, Errors, Duration) → Victoria Metrics
  • ✅ Корреляция трейсов с логами (Loki) и метриками (Victoria Metrics) в Grafana
  • ✅ Tail-based sampling и батчинг для эффективности
  • ✅ Автоматическое масштабирование компонентов Tempo
  • ✅ Prometheus метрики и алерты для всех компонентов

Текущая конфигурация

  • Namespace: tech-tracing
  • OpenTelemetry Collector: 1 реплика (Deployment), централизованный Gateway
  • Tempo Stack: микросервисная архитектура (distributor, ingester, querier, compactor)
  • Storage: MinIO S3 (tempo-traces bucket)
  • Retention: 30 дней (720h)
  • Span Metrics: экспорт в Victoria Metrics (RED метрики)
  • Placement: Может размещаться на любых нодах (masters + workers)

Архитектура

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
┌─────────────────────────────────────────────────────────────┐
│  Application Services                                       │
│  ├── Identity Service (OTLP gRPC)                          │
│  ├── API Gateway (OTLP gRPC)                               │
│  └── Other Services...                                      │
└────────────────┬────────────────────────────────────────────┘
                 │ traces (OTLP gRPC/HTTP port 4317/4318)
                 ▼
┌─────────────────────────────────────────────────────────────┐
│  tech-tracing namespace                                     │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  OpenTelemetry Collector Gateway (Deployment x2)     │  │
│  │  ├── OTLP Receiver (gRPC + HTTP)                     │  │
│  │  ├── Batch Processor                                 │  │
│  │  ├── Memory Limiter                                  │  │
│  │  ├── Span Metrics Processor ─────────┐              │  │
│  │  └── Exporters:                      │              │  │
│  │      ├── OTLP (to Tempo)             │              │  │
│  │      └── PrometheusRemoteWrite ──────┼──────┐       │  │
│  └──────────────┬───────────────────────┘      │       │  │
│                 │ traces                        │       │  │
│  ┌──────────────▼───────────────────────────┐  │       │  │
│  │  Tempo Stack (TempoStack CR)             │  │       │  │
│  │  ├── Distributor (OTLP ingestion)        │  │       │  │
│  │  ├── Ingester (WAL + flushing to S3)     │  │       │  │
│  │  ├── Compactor (retention + compaction)  │  │       │  │
│  │  ├── Querier (trace queries)             │  │       │  │
│  │  ├── Query Frontend (query optimization) │  │       │  │
│  │  └── Gateway (nginx router)              │  │       │  │
│  └──────────────┬───────────────────────────┘  │       │  │
└─────────────────┼────────────────────────────────┼───────┼──┘
                  │ S3 storage                    │       │
                  ▼                               │       │
┌─────────────────────────────────────────┐      │       │
│  tech-minio-tenants namespace           │      │       │
│  MinIO S3 (s3-public tenant)            │      │       │
│  └── Bucket: tempo-traces               │      │       │
│      ├── Trace blocks (compressed)      │      │       │
│      └── Indices                        │      │       │
└─────────────────────────────────────────┘      │       │
                                                  │       │
                                span metrics      │       │
                                                  ▼       │
┌─────────────────────────────────────────────────────────┐
│  tech-monitoring namespace                              │
│  ┌────────────────────────────────────────────────┐    │
│  │  Victoria Metrics                              │    │
│  │  ├── calls_total (request rate)                │◄───┘
│  │  ├── duration_milliseconds_bucket (latency)    │
│  │  └── errors_total                              │
│  └─────────────────┬──────────────────────────────┘    │
│                    │                                    │
│  ┌─────────────────▼──────────────────────────────┐    │
│  │  Grafana                                        │    │
│  │  ├── Tempo datasource (query traces)           │    │
│  │  ├── VictoriaMetrics datasource (metrics)      │    │
│  │  ├── Loki datasource (logs)                    │    │
│  │  └── Correlation: traces ↔ logs ↔ metrics      │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

Поток данных

  1. Сбор трейсов: Приложения отправляют трейсы через OTLP в OTel Collector
  2. Обработка: OTel Collector батчит трейсы, генерирует метрики из спанов
  3. Экспорт трейсов: Трейсы отправляются в Tempo Distributor
  4. Экспорт метрик: Span метрики отправляются в Victoria Metrics
  5. Ingestion: Tempo Ingester записывает трейсы в WAL и периодически флашит в S3
  6. Compaction: Compactor сжимает блоки и применяет retention политики
  7. Запросы: Querier читает трейсы из S3 для ответа на запросы
  8. Визуализация: Grafana запрашивает трейсы через Query Frontend

Быстрый старт

Предварительные требования

  1. Longhorn (для persistent storage)
  2. MinIO S3 (для хранения трейсов)
  3. cert-manager (для webhook сертификатов операторов)
  4. Victoria Metrics (для span метрик)
  5. Grafana (для визуализации)
  6. Подготовленные ноды (labels и taints)

1. Подготовка инфраструктуры

1
2
3
4
5
6
7
8
# Установка зависимостей (если еще не установлены)
cd infra/k8s
make longhorn-install-all
make minio-install-all
make ingress-install-cert-manager

# Подготовка нод
cd ../.. && make k8s-prepare-nodes

2. Создание S3 bucket

Создайте bucket tempo-traces в MinIO:

1
2
cd infra/k8s
make tracing-create-buckets

Команда выведет инструкцию по созданию bucket через MinIO Console.

Рекомендуемая квота: 100GB (для 30 дней retention)

3. Установка операторов

1
make tracing-install-all

Это установит: - Namespace tech-tracing - Resource policies (LimitRange, ResourceQuota, NetworkPolicy) - StorageClass longhorn-tracing - OpenTelemetry Operator - Tempo Operator

4. Создание S3 credentials secret

1
make tracing-create-s3-secret

Команда работает интерактивно: введите MinIO Access Key ID и Secret Access Key когда будет запрошено. Секрет будет создан сразу в кластере.

5. Развертывание Tempo Stack

1
make tracing-install-tempo-stack

Это создаст TempoStack CR, который автоматически развернет все компоненты Tempo.

6. Развертывание OpenTelemetry Collector

1
make tracing-install-otel-collector

Это создаст OpenTelemetryCollector CR с настроенным span metrics processor.

7. Включение мониторинга

1
make tracing-enable-monitoring

Это применит: - ServiceMonitors для сбора метрик - PrometheusRules с алертами

8. Обновление Grafana

1
make monitoring-update-grafana

Это обновит Grafana с добавленным Tempo datasource и корреляцией.

9. Проверка статуса

1
make tracing-status

Ожидаемый результат: - OpenTelemetry Operator pod в Running - Tempo Operator pod в Running - Tempo Stack components pods в Running - OTel Collector pods (2 реплики) в Running - Secret tempo-s3-secret существует

10. Интеграция с приложениями

Обновите конфигурацию ваших сервисов для отправки трейсов в OTel Collector:

1
2
3
4
5
# Было (прямое подключение к Jaeger или другому backend)
collector_url = "jaeger-collector:4317"

# Станет (через OTel Collector Gateway)
collector_url = "otel-gateway-collector.tech-tracing.svc.cluster.local:4317"

Или через переменную окружения:

1
OTEL__COLLECTOR_URL=otel-gateway-collector.tech-tracing.svc.cluster.local:4317

Команды

Установка и обновление

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
make tracing-install-all              # Полная установка стека
make tracing-install-otel-operator    # Только OTel Operator
make tracing-install-tempo-operator   # Только Tempo Operator
make tracing-install-otel-collector   # Deploy OTel Collector CR
make tracing-install-tempo-stack      # Deploy Tempo Stack CR

make tracing-update-otel-operator     # Обновление OTel Operator
make tracing-update-tempo-operator    # Обновление Tempo Operator
make tracing-update-otel-collector    # Обновление OTel Collector CR
make tracing-update-tempo-stack       # Обновление Tempo Stack CR

Управление секретами и S3

1
2
make tracing-create-s3-secret         # Создание S3 credentials secret (интерактивно)
make tracing-create-buckets           # Инструкции по созданию S3 bucket

Мониторинг и отладка

1
2
3
4
5
6
make tracing-status                   # Статус всего стека
make tracing-enable-monitoring        # Включить ServiceMonitors и алерты
make tracing-logs-otel                # Логи OTel Collector
make tracing-logs-tempo               # Логи Tempo (выбор компонента)
make tracing-port-forward-tempo       # Port-forward Tempo (localhost:3200)
make tracing-test-query               # Тест Tempo query API

Удаление

1
make tracing-uninstall                # Удаление стека (УДАЛЯЕТ ДАННЫЕ!)

Справка

1
make tracing-help                     # Справка по командам

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

OpenTelemetry Collector

Конфигурация в manifests/otel-collector.yaml:

Mode: Deployment (централизованный Gateway)

Replicas: 1

Resources: - Requests: 100m CPU, 256Mi RAM - Limits: 500m CPU, 1Gi RAM

Receivers: - OTLP gRPC (port 4317) - OTLP HTTP (port 4318)

Processors: - batch: timeout 10s, send_batch_size 1024 - memory_limiter: limit 80%, spike 25% - resource: добавляет cluster.name - spanmetrics: генерирует RED метрики - Dimensions: http.method, http.status_code, service.name - Latency buckets: 2ms → 15s - Metrics exporter: prometheusremotewrite

Exporters: - otlp: → Tempo Distributor (port 4317) - prometheusremotewrite: → Victoria Metrics

Pipelines: - traces: [otlp] → [memory_limiter, resource, batch, spanmetrics] → [otlp] - metrics: [otlp] → [memory_limiter, batch] → [prometheusremotewrite]

Tempo Stack

Конфигурация в manifests/tempo-stack.yaml:

Storage: - Type: S3 (MinIO) - Secret: tempo-s3-secret - StorageSize: 10Gi (ingester WAL + compactor) - StorageClass: longhorn-tracing

Retention: 720h (30 дней)

Components:

Component Replicas CPU Request Memory Request
Distributor 1 200m 512Mi
Ingester 1 200m 512Mi
Compactor 1 100m 256Mi
Querier 1 200m 512Mi
Query Frontend 1 100m 256Mi
Gateway 1 100m 128Mi

Limits: - Max bytes per trace: 5MB - Ingestion rate limit: 15MB/s - Ingestion burst size: 20MB

Observability: - ServiceMonitors: enabled (автоматически) - Search: enabled - Tracing: sampling_fraction 0.1

Span Metrics

OTel Collector автоматически генерирует следующие метрики в Victoria Metrics:

calls_total: - Labels: service_name, span_name, http_method, http_status_code - Description: Количество запросов

duration_milliseconds_bucket: - Labels: service_name, span_name, le (latency bucket) - Description: Histogram latency для p50, p95, p99

duration_milliseconds_sum / duration_milliseconds_count: - Labels: service_name, span_name - Description: Для вычисления average latency

NetworkPolicy

Конфигурация в manifests/networkpolicy.yaml:

Ingress: - Разрешен от всех namespaces на порты 4317/4318 (OTLP) - Разрешен от всех namespaces на порт 3200 (Tempo query) - Разрешен внутренний трафик между компонентами - Разрешен от monitoring namespace для метрик

Egress: - Разрешен к MinIO (tech-minio-tenants:9000) - Разрешен к Victoria Metrics (tech-monitoring:8428) - Разрешен к Kubernetes API (443, 6443) - Разрешен DNS (53)

Использование

Отправка трейсов из приложений

Python (OpenTelemetry SDK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource

# Конфигурация
resource = Resource.create({"service.name": "my-service"})
provider = TracerProvider(resource=resource)

# OTLP exporter к OTel Collector
otlp_exporter = OTLPSpanExporter(
    endpoint="otel-gateway-collector.tech-tracing.svc.cluster.local:4317",
    insecure=True
)
provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)

# Использование
with tracer.start_as_current_span("operation-name"):
    # Ваш код
    pass

Go (OpenTelemetry SDK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
    "go.opentelemetry.io/otel/sdk/trace"
)

// Setup
exporter, _ := otlptracegrpc.New(
    context.Background(),
    otlptracegrpc.WithEndpoint("otel-gateway-collector.tech-tracing.svc.cluster.local:4317"),
    otlptracegrpc.WithInsecure(),
)
tp := trace.NewTracerProvider(trace.WithBatcher(exporter))
otel.SetTracerProvider(tp)

// Usage
tracer := otel.Tracer("my-service")
ctx, span := tracer.Start(ctx, "operation-name")
defer span.End()

Просмотр трейсов в Grafana

  1. Откройте Grafana: https://grafana.internal.ai-ops.tech
  2. Перейдите в Explore (левое меню)
  3. Выберите datasource: Tempo
  4. Введите search criteria или trace ID
  5. Просмотрите трейс в UI

Корреляция с логами: - Кликните на span → "Logs for this span" - Автоматически откроется Loki с отфильтрованными логами

Корреляция с метриками: - Кликните на span → "Metrics for this span" - Автоматически откроются метрики из Victoria Metrics

Запросы через Tempo API

Поиск трейсов:

1
2
3
4
5
# Через port-forward
make tracing-port-forward-tempo

# В другом терминале
curl 'http://localhost:3200/api/search?tags=service.name=my-service&limit=20'

Получение трейса по ID:

1
curl 'http://localhost:3200/api/traces/<trace-id>'

Метрики из трейсов в Victoria Metrics

Request rate (RPS):

1
sum(rate(calls_total{service_name="my-service"}[5m]))

Error rate:

1
2
3
sum(rate(calls_total{service_name="my-service", http_status_code=~"5.."}[5m]))
/
sum(rate(calls_total{service_name="my-service"}[5m]))

Latency p99:

1
2
3
4
histogram_quantile(
  0.99,
  sum(rate(duration_milliseconds_bucket{service_name="my-service"}[5m])) by (le)
)

Troubleshooting

OTel Collector не запускается

Проблема: Pod в CrashLoopBackOff

Решение:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Проверка логов
make tracing-logs-otel

# Частые причины:
# 1. Неверный endpoint Tempo
kubectl -n tech-tracing get svc | grep tempo

# 2. Неверный endpoint Victoria Metrics
kubectl -n tech-monitoring get svc | grep victoria

# 3. Недостаточно ресурсов
kubectl -n tech-tracing describe pod -l app.kubernetes.io/name=otel-gateway-collector

Tempo Stack не запускается

Проблема: Pods не становятся Ready

Решение:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Проверка статуса TempoStack CR
kubectl -n tech-tracing get tempostack tempo-stack -o yaml

# Проверка логов Tempo Operator
kubectl -n tech-tracing logs -l app.kubernetes.io/name=tempo-operator

# Проверка S3 secret
kubectl -n tech-tracing get secret tempo-s3-secret
kubectl -n tech-tracing describe secret tempo-s3-secret

# Проверка доступности MinIO
kubectl -n tech-minio-tenants get pods

Трейсы не попадают в Tempo

Проблема: Трейсы отправляются, но не видны в Grafana

Решение:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# 1. Проверка метрик OTel Collector
kubectl -n tech-tracing port-forward svc/otel-gateway-collector-monitoring 8888:8888
curl http://localhost:8888/metrics | grep receiver

# Должно быть > 0:
# otelcol_receiver_accepted_spans

# 2. Проверка логов OTel Collector
make tracing-logs-otel

# 3. Проверка Tempo Distributor
make tracing-logs-tempo
# Выберите: 1 (Distributor)

# 4. Проверка connectivity к Tempo
kubectl -n tech-tracing exec -it deployment/otel-gateway-collector -- \
  wget -O- http://tempo-tempo-stack-distributor:4317

Span метрики не попадают в Victoria Metrics

Проблема: Метрики calls_total, duration_* отсутствуют в VM

Решение:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Проверка конфигурации spanmetrics processor
kubectl -n tech-tracing get otelcol otel-gateway -o yaml

# Проверка connectivity к Victoria Metrics
kubectl -n tech-tracing exec -it deployment/otel-gateway-collector -- \
  wget -O- http://vm-victoria-metrics-single-server.tech-monitoring:8428/health

# Проверка метрик в OTel Collector
kubectl -n tech-tracing port-forward svc/otel-gateway-collector-monitoring 8888:8888
curl http://localhost:8888/metrics | grep spanmetrics

# Проверка remote write
curl http://localhost:8888/metrics | grep prometheusremotewrite

S3 storage недоступен

Проблема: Ошибки записи в S3

Решение:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Проверка доступности MinIO
kubectl -n tech-minio-tenants get pods

# Проверка bucket
# MinIO Console → Buckets → tempo-traces (должен существовать)

# Проверка credentials
kubectl -n tech-tracing get secret tempo-s3-secret -o yaml

# Тест подключения из Tempo Ingester
kubectl -n tech-tracing exec -it deployment/tempo-tempo-stack-ingester -- \
  wget -O- http://s3-public-hl.tech-minio-tenants:9000

Высокая latency запросов

Проблема: Запросы трейсов медленные

Решение:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Проверка S3 latency
# MinIO Console → Metrics → Request latency

# Проверка Querier resources
kubectl -n tech-tracing top pod -l app.kubernetes.io/component=querier

# Увеличить replicas Querier
kubectl -n tech-tracing edit tempostack tempo-stack
# spec.template.querier.replicas: 2

# Проверка query patterns
# Используйте более конкретные search tags

Best Practices

Sampling

✅ DO: Используйте tail-based sampling для production

OTel Collector поддерживает tail-based sampling для сохранения только интересных трейсов (ошибки, медленные запросы).

❌ DON'T: Не используйте head-based sampling для критичных операций

Head-based sampling может потерять важные ошибки.

Labels и Tags

✅ DO: Используйте low-cardinality tags

1
2
3
4
# Good
span.set_attribute("service.name", "api")
span.set_attribute("http.method", "GET")
span.set_attribute("environment", "production")

❌ DON'T: Не используйте high-cardinality tags

1
2
3
4
# Bad: создаст миллионы уникальных комбинаций
span.set_attribute("user_id", "12345")
span.set_attribute("request_id", "uuid-...")
span.set_attribute("session_id", "session-...")

Правило: Если значение тега может иметь > 1000 уникальных значений, не используйте его как тег. Добавьте как span event или log.

Resource Management

✅ DO: Мониторьте resource usage

1
2
3
4
5
# CPU и Memory
kubectl -n tech-tracing top pods

# Disk usage (ingester WAL)
kubectl -n tech-tracing exec -it deployment/tempo-tempo-stack-ingester -- df -h

✅ DO: Настройте autoscaling (в будущем)

TempoStack поддерживает HPA для компонентов.

Retention

✅ DO: Настройте retention в соответствии с требованиями

Текущий retention: 30 дней (720h). Для изменения:

1
2
3
4
5
# manifests/tempo-stack.yaml
spec:
  retention:
    global:
      traces: 720h  # Измените при необходимости

✅ DO: Установите квоту на S3 bucket

Рекомендуемая квота: 100GB для 30 дней retention.

Security

✅ DO: Используйте NetworkPolicy

NetworkPolicy уже настроена и ограничивает трафик.

✅ DO: Регулярно ротируйте S3 credentials

1
2
3
4
5
6
7
# 1. Создайте новые credentials в MinIO
# 2. Обновите secret
make tracing-create-s3-secret

# 3. Перезапустите Tempo компоненты
kubectl -n tech-tracing rollout restart deployment/tempo-tempo-stack-distributor
kubectl -n tech-tracing rollout restart statefulset/tempo-tempo-stack-ingester

❌ DON'T: Не храните credentials в Git

Secret файлы (.yaml.example) должны оставаться примерами.

Интеграция с Grafana

Datasource конфигурация

Tempo datasource уже настроен в monitoring/charts/grafana/values.yaml с:

  • tracesToLogsV2: корреляция трейсов → логи (Loki)
  • tracesToMetrics: корреляция трейсов → метрики (Victoria Metrics)
  • serviceMap: карта сервисов из Victoria Metrics
  • search: поиск трейсов в UI
  • nodeGraph: визуализация зависимостей

Дашборды

Рекомендуемые Grafana дашборды:

  • Tempo: импортируйте из grafana.com (ID: 12634)
  • OTel Collector: импортируйте из grafana.com (ID: 15983)
  • RED Metrics: создайте кастомный с использованием span metrics

Дополнительные ресурсы

← Назад к главной документации