← [Раздел](README.md) · [Главная](../README.md)

# Distributed tracing и алерты

## Цель

Понять **распределённую трассировку** (как запрос проходит через сервисы), стандарты **OpenTelemetry**, и как проектировать **алерты**, которые будят on-call по делу, а не по шуму.

## Предварительно

- [Метрики и SLO](metriki-i-slo.md)
- Понимание микросервисной цепочки

## Время

~65 минут

---

## Проблема: «где тормозит?»

Метрика говорит: p99 checkout = 4 с. Логи в трёх сервисах — тысячи строк. **Trace** показывает:

```text
[checkout-api  120ms]
  └─[inventory  80ms]
  └─[payment    3800ms]  ← узкое место
       └─[bank-api 3750ms]
```

Один `trace_id` — вся цепочка.

---

## Основные понятия

| Термин | Описание |
|--------|----------|
| **Trace** | Полный путь одного запроса |
| **Span** | Один участок работы (HTTP вызов, SQL запрос) |
| **Parent / child span** | Иерархия вызовов |
| **Baggage / attributes** | Метаданные: `order_id`, `tenant` |

Визуализация: **waterfall** или **flame graph**.

---

## OpenTelemetry (OTel)

Единый стандарт для инструментирования:

```text
Приложение + OTel SDK → exporter → Jaeger / Tempo / vendor
```

| Компонент | Роль |
|-----------|------|
| **Tracer** | Создаёт span |
| **Propagator** | Передаёт trace context в заголовках (`traceparent`) |
| **Collector** | Приём, обработка, экспорт |

Начните с **auto-instrumentation** HTTP и DB в одном сервисе, затем распространите на исходящие вызовы.

---

## Сэмплиринг

100% трейсов при 10k RPS — дорого.

| Стратегия | Когда |
|-----------|-------|
| **Head sampling** | Фиксированный % (1–10%) |
| **Tail sampling** | Хранить все медленные и ошибочные |
| **Always on** для staging | Отладка |

На проде: **всегда** сэмплируйте ошибки и запросы > SLO latency.

---

## Связка logs + metrics + traces

```text
Алерт: error rate ↑
  → Дашборд: какой endpoint
  → Trace: медленный span payment
  → Log по trace_id: error_code=BANK_TIMEOUT
```

Exemplars в Prometheus связывают точку на графике с конкретным trace_id (если поддерживается стеком).

---

## Алертинг: принципы

Хороший алерт:

1. **Actionable** — есть конкретное действие.
2. **Срочный** — нельзя отложить до утра.
3. **Пользовательский** — влияет на клиента или SLO.

Плохой алерт: «CPU > 70%» без контекста в сервисе с autoscaling.

---

## Типы правил

| Тип | Пример |
|-----|--------|
| **Threshold** | 5xx rate > 1% за 5 мин |
| **Burn rate** | SLO budget burn > 14.4x за 1 ч |
| **Отсутствие данных** | Нет метрик — агент упал |
| **Синтетика** | Probe с внешней точки не отвечает |

Используйте **многоуровневую** эскалацию: warning в Slack → critical в PagerDuty.

---

## On-call и runbook

К каждому критичному алерту — **runbook** (1 страница):

1. Что означает.
2. Первые шаги диагностики (ссылки на дашборды).
3. Известные причины и фиксы.
4. Когда эскалировать.
5. Как откатить релиз.

Без runbook on-call открывает Google в 3 ночи.

---

## Alert fatigue

| Симптом | Лечение |
|---------|---------|
| 50 алертов в день | Удалить дубли, повысить пороги |
| Всегда «игнорим» | Убрать или понизить до ticket |
| Нет владельца сервиса | Команда отвечает за свои алерты |

Правило: если алерт не требовал действия 3 раза подряд — пересмотреть.

---

## Status page и коммуникация

При нарушении SLO:

- внутренний канал `#incidents`;
- внешняя status page (`status.example.com`);
- постмортем в течение 5 рабочих дней (blameless).

---

## Минимальный стек для учебного проекта

1. OTel в API + передача `traceparent` в downstream.
2. Prometheus: RED метрики.
3. Grafana: дашборд + один burn-rate алерт.
4. Runbook в `docs/runbooks/checkout-errors.md`.

---

## Самопроверка

1. Чем span отличается от trace?
2. Зачем нужен сэмплиринг трейсов?
3. Назовите три свойства хорошего алерта.
4. Что такое burn rate в контексте SLO?

---

## Дальше

→ [Раздел 09 — Тестирование](../09-testing/README.md)  
← [Метрики и SLO](metriki-i-slo.md)