Troubleshooting и best practices

Типичные проблемы

Проблема 1: Spans не появляются в Jaeger

Симптомы: Приложение работает, но traces не видны в UI.

Debugging:

1. Проверьте exporter в приложении:

// Добавьте ConsoleSpanExporter для debug
const { ConsoleSpanExporter } = require("@opentelemetry/sdk-trace-base");
 
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));

2. Проверьте Collector:

curl http://otel-collector:13133
# Response: {"status":"Server available"}

3. Проверьте метрики:

rate(otelcol_receiver_accepted_spans[5m])  # > 0?
rate(otelcol_exporter_sent_spans[5m])      # > 0?

Частые причины:

• ❌ Неправильный URL exporter
• ❌ Sampling = 0%
• ❌ Collector не запущен
• ❌ Network issue

Проблема 2: Broken Traces (spans не связаны)

Симптомы: В Jaeger два trace вместо одного.

Причина: Context propagation не работает.

Решение:

// Проверьте headers
console.log("traceparent:", req.headers.traceparent);
 
// Если пусто → добавьте manual propagation (урок 05)

Проблема 3: High Cardinality Attributes

Симптомы: Огромное количество уникальных traces, Jaeger тормозит.

Причина: Атрибуты с высокой cardinality (user.id, order.id).

Плохо:

span.setAttribute("order.id", orderId); // 1M уникальных значений

Хорошо:

// Используйте для фильтрации, но не для aggregation
span.setAttribute("order.status", "pending"); // 3-5 значений

Production Deployment Checklist

✅ Перед Production

Infrastructure:

• OTel Collector развёрнут (HA setup)
• Jaeger/Tempo backend готов
• Prometheus мониторинг настроен
• Grafana dashboards созданы

Configuration:

• Sampling настроен (1-5%)
• BatchSpanProcessor включён
• PII redaction настроен
• TLS enabled
• Health checks отфильтрованы

Monitoring:

• Alerts на dropped spans
• Alerts на Collector errors
• CPU/Memory limits установлены
• Retention policy настроен (7-30 days)

Production Best Practices

1. Начните с одного сервиса

Не делайте: Включить трассировку сразу на всех 50 сервисах.

Делайте: Pilot на 1-2 критичных сервисах → оцените overhead → rollout.

2. Мониторьте overhead

// Добавьте метрики
const tracingOverhead = new promClient.Gauge({
  name: "tracing_overhead_cpu_percent",
  help: "CPU overhead from tracing",
});
 
setInterval(() => {
  const cpuUsage = process.cpuUsage();
  tracingOverhead.set(calculateOverhead(cpuUsage));
}, 60000);

3. Rollout Strategy

Week 1: Dev environment (100% sampling) Week 2: Staging (10% sampling) Week 3: Production (1% sampling) Week 4: Tail-sampling enabled

4. Documentation

Документируйте для команды:

• Как найти trace по request_id
• Как от alert перейти к trace
• Какие атрибуты логировать
• PII policy

Полезные инструменты

1. Jaeger HotROD Demo

docker run --rm -p 8080:8080 -p 16686:16686 \
  jaegertracing/example-hotrod:latest all

2. OpenTelemetry Demo

https://github.com/open-telemetry/opentelemetry-demo

3. Grafana Cloud (бесплатный tier)

Заключение курса

Поздравляем! Вы прошли полный курс по distributed tracing от основ до production.

Что вы теперь умеете:

Следующие шаги:

1. Внедрите трассировку в ваш проект
2. Начните с 1% sampling
3. Постепенно расширяйте на другие сервисы
4. Делитесь знаниями с командой

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

• OpenTelemetry Documentation
• Jaeger Documentation
• W3C Trace Context
• Google Dapper Paper