diff --git a/openspec/changes/add-lab6-telemetry-pipeline/.openspec.yaml b/openspec/changes/add-lab6-telemetry-pipeline/.openspec.yaml new file mode 100644 index 0000000..5c99d6d --- /dev/null +++ b/openspec/changes/add-lab6-telemetry-pipeline/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-29 diff --git a/openspec/changes/add-lab6-telemetry-pipeline/design.md b/openspec/changes/add-lab6-telemetry-pipeline/design.md new file mode 100644 index 0000000..34bbada --- /dev/null +++ b/openspec/changes/add-lab6-telemetry-pipeline/design.md @@ -0,0 +1,70 @@ +## Context + +Решение лабы 5 — три процесса из одного образа (gunicorn с двумя `UvicornWorker` в каждой из двух реплик API, `relay`, `worker` на FastStream), журнал — structlog за портом `Logger` с allowlist полей в stdout. Телеметрии нет. Заготовки `.prep/lab6` (конфиги Collector 0.163, Prometheus 3.15, Loki 3.7, Tempo 2.10, Grafana 12.4, dashboards, `obs_check.py`) проверены на заглушке приложения; их сети не согласованы со стендом лабы 5 (`backend` internal + `edge`). + +Версии (PyPI на 2026-10-29, Python 3.14 поддерживается): `opentelemetry-api/sdk` и `opentelemetry-exporter-otlp-proto-http` 1.45.1, `opentelemetry-instrumentation-fastapi`/`-asyncpg` 0.66b1, `faststream[rabbit,otel]` 0.7.8 — закреплены в `uv.lock`. + +## Goals / Non-Goals + +**Goals:** сигналы уровня «3» `contracts/observability.md` от API, relay и worker; Collector и три хранилища с volumes; Grafana из provisioning; поиск запроса и job по логу и трассе; отсутствие секретов; `make test` при включённой телеметрии. + +**Non-Goals:** перенос контекста через outbox/брокер, producer spans, spans S3, queue/pool/saturation/CPU, time to ready, alerts — уровень «4»; sampling — трек 1. + +## Decisions + +### 1. SDK в `shared/infrastructure/telemetry.py`, запуск после fork + +`start_telemetry(settings, allowed_fields, service)` создаёт `TracerProvider`, `MeterProvider`, `LoggerProvider` с общим `Resource`, ставит их глобальными, включает инструментацию asyncpg и возвращает объект `Telemetry` (или `None`, если `OTEL_SDK_DISABLED=true` либо нет `OTEL_EXPORTER_OTLP_ENDPOINT`). Вызывается в `create_app()` — gunicorn с `preload_app = False` импортирует приложение в каждом воркере уже после fork, master только читает `LOG_FIELDS` и SDK не создаёт; в `create_worker()` и `relay.serve()` — в единственном процессе сервиса. Render-процессы worker создаются `ProcessPoolExecutor` со стартом `forkserver` (умолчание Python 3.14 на Linux) и провайдеры не наследуют. + +- Получаем: потоки `Batch*Processor` живут в том процессе, который пишет данные; `service.instance.id = -` различает cumulative-серии двух воркеров одной реплики. +- Стоит: инструментации берут глобальные провайдеры — в одном процессе одна телеметрия (для тестов SDK выключен: адреса Collector нет). + +Экспорт — OTLP/HTTP protobuf (без gRPC), только `BatchSpanProcessor`, `BatchLogRecordProcessor`, `PeriodicExportingMetricReader` (интервал `OTEL_METRIC_EXPORT_INTERVAL=10000`), таймаут `OTEL_EXPORTER_OTLP_TIMEOUT=2` (секунды — проверено по исходнику экспортёра 1.45), очереди `OTEL_BSP_MAX_QUEUE_SIZE`/`OTEL_BLRP_MAX_QUEUE_SIZE=2048`: при недоступном Collector записи отбрасываются, запрос не ждёт. Провайдеры создаются с `shutdown_on_exit=False`, а `Telemetry.shutdown(timeout)` выполняет их остановку в daemon-потоке с `join(timeout)` (`TELEMETRY_SHUTDOWN_SECONDS=2`): штатный `BatchProcessor.shutdown()` ждёт до 30 с, что не помещается в `stop_grace_period`. + +Sampler — `ParentBased(root=ServerRoots())`: корневые spans видов `SERVER`, `CONSUMER`, `PRODUCER` записываются, корневые `CLIENT`/`INTERNAL` — нет. Иначе каждая проверка `/health/ready` балансировщиком (раз в секунду на реплику), опрос outbox relay и уборка давали бы отдельную трассу из одного `SELECT`. Вложенные spans PostgreSQL наследуют решение родителя. + +### 2. Сигналы и их источники + +| Сигнал `observability.md` | Источник | Prometheus / Loki / Tempo | Labels | +| --- | --- | --- | --- | +| HTTP requests, duration | `FastAPIInstrumentor.instrument_app` (`OTEL_SEMCONV_STABILITY_OPT_IN=http` по умолчанию из кода), `excluded_urls` `/health/`, без внутренних spans `send`/`receive` | `http_server_request_duration_seconds_*`, buckets 5 мс…10 с из semconv | `http_request_method`, `http_route`, `http_response_status_code`; класс — recording rule | +| Jobs processed/failed | порт `JobObserver` зоны `attachments`, адаптер на OTel API | `messenger_jobs_processed_total` | `job_type`, `outcome` | +| Job duration | тот же адаптер, `explicit_bucket_boundaries_advisory` 0.05…60 с | `messenger_job_duration_seconds_*` | `job_type`, `outcome` | +| Логи | `OtlpLogHandler` на root logger | Loki `{service_name}`, атрибуты — structured metadata | индекс только `service_name`, `deployment_environment_name` | +| Server spans | FastAPI-инструментация + `messenger.request_id` из конвейера | Tempo | — | +| Consumer spans | `RabbitTelemetryMiddleware` FastStream на брокере worker + атрибуты из `JobObserver` | Tempo | — | +| DB spans | `AsyncPGInstrumentor` | Tempo | — | + +Buckets job duration `0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 30, 60`: thumbnail, crop и optimized fixture строятся за сотни миллисекунд, предел рендера — 30 с, `JOB_TIMEOUT_SECONDS=60`. Метрики FastStream-middleware (`messaging.process.duration` с buckets по умолчанию до 10000 «секунд») отбрасываются View с `DropAggregation`: они дублируют `messenger.job.duration` хуже. + +Исход доставки берётся из `Outcome` обработчика (`done`, `retry_scheduled`, `failed`, `duplicate_noop`, `fenced`) или `error`, если обработчик бросил исключение и сообщение вернулось в очередь. Статус consumer span — `ERROR` для `retry_scheduled`, `failed`, `error`: middleware FastStream этого не знает, обработчик ловит исключения сам. + +### 3. Порт `JobObserver` вместо OTel в точке входа + +`attachments/application/ports.py`: `JobObserver.observe(job, outcome, seconds)`; адаптер `OtelJobObserver` в `attachments/infrastructure/telemetry.py` (counter, histogram, атрибуты текущего span); провайдер в `WorkerProvider`. Точка входа `handle_job` меряет время, вызывает порт и пишет `job.processed` через `Logger`. + +- Получаем: точка входа и слой приложения не импортируют OTel; без SDK адаптер работает на no-op провайдере API. +- Стоит: ещё один порт и провайдер. + +### 4. Логи: одна запись — stdout и OTLP + +structlog-процессор `add_trace_context` кладёт `trace_id`/`span_id` текущего span в запись (они добавлены в `PLATFORM_FIELDS`). `OtlpLogHandler` (stdlib-handler на root logger, рядом с stdout-handler) берёт словарь события structlog (`record.msg`), пропускает только поля allowlist процесса (без `trace_id`/`span_id`, их SDK ставит из контекста) и отдаёт `body=event`, `event_name=event`, атрибут `event`, severity по уровню. Записи сторонних библиотек идут с `body` = сообщение; записи логгеров `opentelemetry.*` handler пропускает, чтобы ошибки экспорта не порождали новые записи экспорта. Стандартный `LoggingHandler` SDK не подходит: он кладёт весь словарь structlog в `body` и служебные `_logger`/`_name` в атрибуты. + +Отложенные подписчики `EventBus` (журналы `audit.*`) выполняются в фоне; очередь теперь хранит пару (событие, `contextvars.copy_context()`), а обработчик запускается задачей в этом контексте. Так `audit.attachment_queued` и `audit.job_settled` получают trace context запроса/задания, а contextvars structlog — тот же снимок. + +### 5. Стенд + +Из `.prep/lab6` переносятся `infra/otel/collector.yaml` (без `docker_stats` — уровень «4»), `infra/prometheus/prometheus.yml` (без `scrape.d`), `infra/prometheus/rules/messenger.recording.yml` (группы HTTP и jobs), `infra/loki/loki.yaml`, `infra/tempo/tempo.yaml`, `infra/grafana/provisioning`, dashboards `messenger-api` и `messenger-pipeline` (только панели уровня «3»), `scripts/obs_check.py`, `scripts/obs-validate.sh`, `scripts/secrets-lab6.sh`. Сервисы фрагмента вливаются в `compose.yaml`; сети — те, что в лабе 5: Collector и Prometheus в `backend` и `edge` (OTLP от приложения во внутренней сети), Loki, Tempo, Grafana — в `edge`, без `networks:` они попали бы в `default`, куда приложение не подключено. `depends_on` приложения от телеметрии нет. + +Лимиты: Collector 0.5 CPU/256M (`memory_limiter` 75%, `GOMEMLIMIT=200MiB`), Prometheus 0.5/512M, Loki 0.5/384M, Tempo 0.5/384M, Grafana 0.5/384M. Порты на `127.0.0.1`: `PROMETHEUS_PORT` 9090, `LOKI_PORT` 3100, `TEMPO_PORT` 3200, `GRAFANA_PORT` 3000. + +## Risks / Trade-offs + +- [Потери при недоступном Collector] → очереди SDK 2048 и отбрасывание; учёт потерь — уровень «4». +- [Cardinality `instance`: 2 реплики × 2 воркера × перезапуски] → retention 7 дней, labels без бизнес-ID, проверка `count by (__name__)`. +- [trace_id в логе при head sampling трека 1 может указывать на несохранённую трассу] → объясняется в треке. +- [Collector, Loki, Tempo без shell] → healthcheck через статический busybox из одноразового `healthtools`. + +## Migration Plan + +Схема БД и API не меняются. `make secrets` дописывает пароль Grafana; `make up` поднимает новые сервисы рядом с прежними; откат — образ лабы 5 и `docker compose rm` сервисов телеметрии (volumes остаются). diff --git a/openspec/changes/add-lab6-telemetry-pipeline/proposal.md b/openspec/changes/add-lab6-telemetry-pipeline/proposal.md new file mode 100644 index 0000000..e0f6d6b --- /dev/null +++ b/openspec/changes/add-lab6-telemetry-pipeline/proposal.md @@ -0,0 +1,31 @@ +## Why + +Решение лабы 5 видно только через stdout-журнал контейнеров: нет метрик, трасс и места, где их можно сопоставить. Рубрика «3» лабы 6 требует, чтобы весь минимум lab5 работал внутри общего стенда с Collector, хранилищами трёх сигналов и Grafana, API и worker отдавали OTLP, в Grafana были RED API, jobs по исходу и duration worker, структурные логи и реальные трассы, импортируемый dashboard, низкая кардинальность и отсутствие секретов, а контролируемый запрос и job находились по трассе и логу. Изменение закрывает уровень «3» и строки 3.1–3.9 `REPORT.md`. + +## What Changes + +- Каждый процесс (gunicorn-воркер API, relay, worker) после fork поднимает OpenTelemetry SDK с resource `service.name` (`messenger-api` / `messenger-relay` / `messenger-worker`), `service.version`, `service.instance.id` = `-`, `deployment.environment.name=lab`; экспорт OTLP/HTTP только batch-процессорами, `OTEL_SDK_DISABLED=true` выключает SDK и инструментации. +- HTTP: server span и histogram `http.server.request.duration` (секунды, шаблон маршрута, метод, код) без `/health/*`; атрибут `messenger.request_id` = `X-Request-Id`; client spans PostgreSQL внутри запросов и заданий. +- Worker: consumer span каждой доставки с `messenger.job_id`, `messenger.attachment_id`, `messenger.job.attempt`, `messenger.job.outcome`; counter `messenger.jobs.processed` и histogram `messenger.job.duration` по `job.type` и `outcome`; запись `job.processed`. +- Логи: та же allowlist-запись, что в stdout, уходит OTLP в Loki с `event`, severity, `trace_id`/`span_id`; отложенные подписчики событий выполняются в контексте, где событие возникло. +- Стенд: `otel-collector` (contrib, memory_limiter → redaction → batch, ограниченные очереди), `prometheus` (OTLP-приём, recording rules RED), `loki`, `tempo`, `grafana` (datasources и dashboards из `infra/grafana`), volumes, секрет пароля Grafana; порты наблюдаемости только на `127.0.0.1`. +- Обвязка: `scripts/obs_check.py`, `scripts/obs-validate.sh`, `scripts/secrets-lab6.sh` из `.prep/lab6`; цели `obs-validate`, `telemetry-check`. + +## Capabilities + +### New Capabilities +- `lab6-service-telemetry`: SDK в процессах, resource attributes, HTTP- и job-метрики, логи с trace context, server/consumer/DB spans, запрет секретов и тел, выключатель SDK, независимость запросов и готовности от телеметрии. +- `lab6-telemetry-stack`: Collector, Prometheus, Loki, Tempo и Grafana в стенде, provisioning и volumes, опубликованные порты, проверки конфигурации. + +### Modified Capabilities +- `lab1-service-operability`: «Единый журнал всех сообщений процесса» — записи несут `trace_id`/`span_id` и дублируются в OTLP. + +## Impact + +- Код: `shared/infrastructure/telemetry.py` и журнал, `shared/application/messagebus.py`, конвейер запроса, порт учёта заданий зоны `attachments`, сборки `main.py`, `relay.py`, `worker.py`; зависимости OpenTelemetry API/SDK, OTLP/HTTP exporter, инструментации FastAPI и asyncpg, `faststream[otel]`. +- Стенд: `compose.yaml`, `infra/otel`, `infra/prometheus`, `infra/loki`, `infra/tempo`, `infra/grafana`, `scripts/`, `Makefile`, `.env.example`. +- Отчёт: строки уровня «3» `REPORT.md`, `evidence/`. + +## Non-goals + +Перенос W3C context через outbox и брокер, producer spans relay, spans S3, queue depth/age, DB pool, saturation worker, CPU/RAM контейнеров, time to ready, alert rules, runbooks и инциденты — уровень «4», следующее изменение; sampling и матрица стоимости — трек 1. Из Out of scope не появляется ничего: TLS (лаба 7), burn-rate alerts (трек 2), внешняя доставка alerts, кластерные хранилища телеметрии. diff --git a/openspec/changes/add-lab6-telemetry-pipeline/specs/lab1-service-operability/spec.md b/openspec/changes/add-lab6-telemetry-pipeline/specs/lab1-service-operability/spec.md new file mode 100644 index 0000000..27bd0f9 --- /dev/null +++ b/openspec/changes/add-lab6-telemetry-pipeline/specs/lab1-service-operability/spec.md @@ -0,0 +1,20 @@ +## MODIFIED Requirements + +### Requirement: Единый журнал всех сообщений процесса + +Сервис SHALL выводить в stdout единый поток структурированных записей. Сообщения сервера приложений и используемых библиотек SHALL проходить через тот же журнал и иметь тот же формат, что и сообщения приложения. Записи SHALL содержать только поля из объявленного перечня; поля вне перечня SHALL отбрасываться. Запись, сделанная при активном span трассировки, SHALL содержать поля `trace_id` и `span_id`. Когда телеметрия включена, каждая запись журнала SHALL также экспортироваться по OTLP с тем же перечнем полей. + +#### Scenario: Сообщения сервера приложений в общем формате + +- **WHEN** процесс запускается и печатает сообщения о старте сервера +- **THEN** каждая строка stdout разбирается как структурированная запись того же формата, что и записи приложения + +#### Scenario: Незаявленное поле не попадает в журнал + +- **WHEN** запись журнала формируется с полем, отсутствующим в перечне разрешённых +- **THEN** это поле в выводе отсутствует и в stdout, и в OTLP-записи + +#### Scenario: Запись запроса связана с трассой + +- **WHEN** телеметрия включена и API обработал бизнес-запрос +- **THEN** запись `request.handled` в stdout содержит `trace_id` и `span_id` server span этого запроса diff --git a/openspec/changes/add-lab6-telemetry-pipeline/specs/lab6-service-telemetry/spec.md b/openspec/changes/add-lab6-telemetry-pipeline/specs/lab6-service-telemetry/spec.md new file mode 100644 index 0000000..8342740 --- /dev/null +++ b/openspec/changes/add-lab6-telemetry-pipeline/specs/lab6-service-telemetry/spec.md @@ -0,0 +1,123 @@ +## Purpose + +Определяет телеметрию процессов мессенджера: какие метрики, логи и трассы отдают API, relay и worker, с какими resource attributes и labels, что в них запрещено и как телеметрия соотносится с обслуживанием запросов. + +## ADDED Requirements + +### Requirement: Телеметрия процесса и resource attributes + +Каждый процесс приложения (рабочий процесс API, relay, worker) SHALL экспортировать метрики, логи и трассы по OTLP/HTTP в Collector, адрес которого задаётся `OTEL_EXPORTER_OTLP_ENDPOINT`. Телеметрия процесса SHALL нести resource attributes `service.name` (`messenger-api`, `messenger-relay`, `messenger-worker`; переопределяется `OTEL_SERVICE_NAME`), `service.version` (версия пакета), `service.instance.id`, уникальный для каждого процесса (идентификатор реплики и номер процесса), и `deployment.environment.name=lab` из `OTEL_RESOURCE_ATTRIBUTES`. В Prometheus `service.name` SHALL становиться label `job`, а `service.instance.id` — label `instance`. При `OTEL_SDK_DISABLED=true` или без адреса Collector процесс SHALL NOT создавать экспортёры и инструментации и SHALL обслуживать запросы как без телеметрии. + +#### Scenario: Сервисы различимы + +- **WHEN** стенд обработал запросы и задания +- **THEN** в Prometheus есть серии с `job="messenger-api"` и `job="messenger-worker"`, у двух реплик API и двух рабочих процессов каждой реплики разные значения `instance` + +#### Scenario: Окружение помечено + +- **WHEN** в Loki запрашиваются потоки `{service_name="messenger-api"}` +- **THEN** у потока есть label `deployment_environment_name="lab"` + +#### Scenario: SDK выключен + +- **WHEN** процесс запущен с `OTEL_SDK_DISABLED=true` при заданном адресе Collector +- **THEN** телеметрия не запускается, глобальные провайдеры OpenTelemetry остаются заглушками, а API отвечает на запросы как обычно + +### Requirement: Метрики HTTP API + +API SHALL записывать histogram длительности запроса в секундах (`http.server.request.duration`, в Prometheus `http_server_request_duration_seconds_bucket|_sum|_count`) с labels метода (`http_request_method`), шаблона маршрута (`http_route`, например `/api/v1/chats/{chat_id}/messages`) и кода ответа (`http_response_status_code`). Число запросов SHALL выводиться из `_count` той же histogram, класс статуса — из кода ответа recording rule `messenger:http_requests:rate2m{status_class}`. Пробы `/health/live` и `/health/ready` SHALL NOT попадать в эти метрики. Labels SHALL NOT содержать идентификаторы пользователей, чатов, сообщений, вложений, запросов, сырой путь, query string и filename. + +#### Scenario: Маршрут записан шаблоном + +- **WHEN** участник отправляет сообщение в чат с конкретным UUID +- **THEN** в Prometheus растёт `http_server_request_duration_seconds_count{http_route="/api/v1/chats/{chat_id}/messages",http_request_method="POST",http_response_status_code="201"}`, а UUID чата не встречается ни в одном значении label + +#### Scenario: Ошибки различимы по классу + +- **WHEN** клиент получает `401` на неверный пароль и `404` на чужой чат +- **THEN** recording rule `messenger:http_requests:rate2m` показывает их в `status_class="4xx"`, отдельно от `2xx` и `5xx` + +#### Scenario: Пробы не учитываются + +- **WHEN** балансировщик и healthcheck опрашивают `/health/ready` каждую секунду +- **THEN** серий с `http_route=~"/health/.*"` в Prometheus нет + +### Requirement: Метрики обработки заданий + +Worker SHALL на каждую доставку задания увеличивать counter `messenger.jobs.processed` (в Prometheus `messenger_jobs_processed_total`) и записывать histogram `messenger.job.duration` в секундах (`messenger_job_duration_seconds_*`) с labels `job_type` (`attachment.process.v1`) и `outcome` — исход доставки: `done`, `retry_scheduled`, `failed`, `duplicate_noop`, `fenced` или `error` (исключение, сообщение возвращено в очередь). Границы buckets SHALL покрывать диапазон от десятков миллисекунд до минуты. Labels SHALL NOT содержать идентификаторы задания и вложения. + +#### Scenario: Успешная обработка учтена + +- **WHEN** загруженное изображение стало `ready` +- **THEN** `messenger_jobs_processed_total{job="messenger-worker",job_type="attachment.process.v1",outcome="done"}` вырос, а `messenger_job_duration_seconds_count` с теми же labels вырос на столько же + +#### Scenario: Финальная ошибка учтена + +- **WHEN** задание завершилось `failed` (`invalid_image`) +- **THEN** растёт серия с `outcome="failed"`, а не `done` + +#### Scenario: Повторная доставка учтена отдельно + +- **WHEN** то же сообщение задания доставлено повторно после `ready` +- **THEN** растёт серия с `outcome="duplicate_noop"` + +### Requirement: Структурные логи в хранилище логов + +Каждая запись журнала процесса SHALL уходить и в stdout, и по OTLP в хранилище логов с timestamp, severity, `service.name` и `event`; поля записи из перечня журнала (например `request_id`, `route`, `status`, `job_id`, `attachment_id`, `outcome`) SHALL становиться атрибутами записи. Запись, сделанная при активном span, SHALL нести его `trace_id` (32 hex) и `span_id` (16 hex); записи отложенных подписчиков событий SHALL нести контекст операции, породившей событие. API SHALL писать запись `request.handled` на каждый запрос, worker — запись `job.processed` на каждую доставку задания с `job_id`, `attachment_id`, `attempt`, `outcome` и длительностью. Поля вне перечня, текст сообщения, пароль, токен, `Authorization`, filename и байты изображения SHALL NOT попадать в записи. + +#### Scenario: Лог запроса находится по X-Request-Id + +- **WHEN** клиент выполнил `POST /api/v1/users` и получил `X-Request-Id` = `R` +- **THEN** запрос Loki `{service_name="messenger-api"} | request_id="R"` возвращает запись `request.handled` с непустыми `trace_id` и `span_id` + +#### Scenario: Лог задания находится по вложению + +- **WHEN** загруженное вложение `A` стало `ready` +- **THEN** запрос Loki `{service_name="messenger-worker"} | attachment_id="A"` возвращает запись `job.processed` с `outcome="done"` и `trace_id` трассы обработки + +#### Scenario: Запись без активного span + +- **WHEN** процесс пишет запись вне запроса и задания (например `service.started`) +- **THEN** запись есть в Loki без `trace_id` + +### Requirement: Трассы API и worker + +API SHALL создавать server span на каждый бизнес-запрос (имя — метод и шаблон маршрута, атрибуты `http.request.method`, `http.route`, `http.response.status_code`, `messenger.request_id` = `X-Request-Id`, статус `ERROR` для `5xx`) и client spans PostgreSQL внутри него. Worker SHALL создавать consumer span на каждую доставку задания с атрибутами `messenger.job_id`, `messenger.attachment_id`, `messenger.job.attempt`, `messenger.job.outcome` и статусом `ERROR` при исходах `retry_scheduled`, `failed`, `error`, с client spans PostgreSQL внутри. Запросы к PostgreSQL вне запроса или задания (опрос outbox, проверки готовности, уборка) SHALL NOT порождать отдельные трассы. Пробы `/health/*` SHALL NOT порождать трассы. Атрибуты spans SHALL NOT содержать заголовки HTTP, query string, тело запроса, текст сообщения, пароль и токен. + +#### Scenario: Трасса запроса + +- **WHEN** клиент выполнил `POST /api/v1/users` с `X-Request-Id` = `R` +- **THEN** TraceQL `{ span.messenger.request_id = "R" }` в Tempo находит трассу с server span `POST /api/v1/users` и дочерними spans PostgreSQL + +#### Scenario: Трасса задания + +- **WHEN** вложение `A` обработано worker +- **THEN** TraceQL `{ span.messenger.attachment_id = "A" }` находит трассу `messenger-worker` с consumer span, `messenger.job.outcome="done"` и spans PostgreSQL + +#### Scenario: Ошибка видна в трассе + +- **WHEN** запрос завершился `503 unavailable` +- **THEN** server span этого запроса имеет статус `ERROR` и `http.response.status_code=503` + +### Requirement: Телеметрия не мешает обслуживанию + +Экспорт телеметрии SHALL выполняться в фоне ограниченными очередями: недоступность Collector или хранилищ телеметрии SHALL NOT увеличивать время ответа API на величину таймаута экспорта, SHALL NOT менять ответы API и SHALL NOT переводить `/health/ready` в `503`. При остановке процесса досылка телеметрии SHALL ограничиваться несколькими секундами и укладываться в окно корректного завершения. + +#### Scenario: Collector остановлен + +- **WHEN** `otel-collector` остановлен, а клиент выполняет `make test` +- **THEN** smoke проходит, `/health/ready` отвечает `200` + +#### Scenario: Остановка процесса при недоступном Collector + +- **WHEN** `otel-collector` остановлен, а реплика API получает `SIGTERM` +- **THEN** процесс завершается с кодом 0 в пределах `stop_grace_period` + +### Requirement: Секреты и содержимое не попадают в телеметрию + +Пароль, токен сессии, значение `Authorization`, текст сообщения, filename и байты изображения SHALL NOT встречаться ни в хранилище логов, ни в хранилище трасс. Collector SHALL дополнительно маскировать атрибуты с именами паролей, токенов, секретов, заголовков HTTP, `url.query` и значения вида `Bearer …`/`Basic …` во всех pipeline. + +#### Scenario: Поиск известных значений + +- **WHEN** клиент регистрируется с паролем-маркером, входит, отправляет сообщение с текстом-маркером, загружает файл с filename-маркером и выходит +- **THEN** поиск каждого маркера и токена по Loki (`|=`) и по сырым трассам Tempo за это окно даёт 0 совпадений diff --git a/openspec/changes/add-lab6-telemetry-pipeline/specs/lab6-telemetry-stack/spec.md b/openspec/changes/add-lab6-telemetry-pipeline/specs/lab6-telemetry-stack/spec.md new file mode 100644 index 0000000..4217725 --- /dev/null +++ b/openspec/changes/add-lab6-telemetry-pipeline/specs/lab6-telemetry-stack/spec.md @@ -0,0 +1,56 @@ +## Purpose + +Определяет стек наблюдаемости в стенде: Collector, хранилища метрик, логов и трасс и Grafana, их конфигурацию и provisioning в Git, volumes, опубликованные порты и проверки конфигурации. + +## ADDED Requirements + +### Requirement: Collector, хранилища и Grafana в общем стенде + +Стенд SHALL поднимать одной командой `make up` вместе с приложением сервисы `otel-collector` (OpenTelemetry Collector contrib), `prometheus` (метрики), `loki` (логи), `tempo` (трассы) и `grafana`; образы SHALL быть закреплены тегом и digest, контейнеры SHALL работать не от root с лимитами CPU и памяти и healthcheck, который доходит до `healthy`. Collector SHALL принимать OTLP/HTTP только во внутренних сетях стенда и раскладывать метрики в Prometheus, логи в Loki, трассы в Tempo; в каждом pipeline SHALL стоять ограничитель памяти, маскирование и батчинг, а экспортёры SHALL иметь ограниченную очередь и ограниченный по времени повтор. Приложение SHALL NOT зависеть от готовности этих сервисов при старте. + +#### Scenario: Стенд из чистого состояния + +- **WHEN** после `make reset-data` выполняется `make up` +- **THEN** `docker compose ps` показывает `otel-collector`, `prometheus`, `loki`, `tempo`, `grafana` в состоянии `healthy` рядом с `lb`, `api` ×2, `relay`, `worker`, `postgres`, `valkey`, `s3`, `broker` + +#### Scenario: OTLP не опубликован + +- **WHEN** проверяются опубликованные порты стенда +- **THEN** порты 4318 и 8888 Collector не опубликованы на хост, а Prometheus, Loki, Tempo и Grafana опубликованы только на `127.0.0.1` + +### Requirement: Конфигурация и provisioning в Git + +Конфигурация Collector, Prometheus (включая recording rules), Loki, Tempo, datasources и dashboards Grafana SHALL лежать в `infra/` и подключаться в контейнеры только для чтения. Grafana SHALL при старте импортировать datasources с фиксированными uid `prometheus`, `loki`, `tempo` и связями trace ↔ log, а также dashboards из JSON в Git без ручных действий; dashboards SHALL ссылаться только на существующие имена метрик. `make obs-validate` SHALL проверять конфигурацию Collector его же бинарником, конфигурацию и rules Prometheus — `promtool`, конфигурации Loki и Tempo — их бинарниками, dashboards — как валидный JSON с uid и панелями. + +#### Scenario: Provisioning импортирован + +- **WHEN** стенд поднят из чистого состояния +- **THEN** API Grafana показывает три datasource со статусом `OK` и dashboards `messenger-api` и `messenger-pipeline` с `provisioned: true` в папке Messenger + +#### Scenario: Dashboard показывает данные приложения + +- **WHEN** выполнен `make test` и создана нагрузка +- **THEN** каждый запрос панелей к Prometheus выполняется без ошибок и ссылается на существующие метрики, панели RPS, ошибок, длительности API и jobs по исходу возвращают серии `job="messenger-api"`/`job="messenger-worker"` + +#### Scenario: Ошибка конфигурации ловится до запуска + +- **WHEN** выполняется `make obs-validate` +- **THEN** команда завершается кодом 0 и печатает успешную проверку Collector, Prometheus, Loki, Tempo и dashboards + +### Requirement: История телеметрии переживает рестарт + +Prometheus, Loki, Tempo и Grafana SHALL хранить данные в именованных volumes с ограниченным retention; рестарт этих сервисов без удаления volumes SHALL сохранять ранее записанные метрики, логи и трассы. Удаление учебных данных SHALL выполняться только явной командой `make reset-data`. + +#### Scenario: Рестарт хранилищ + +- **WHEN** найден лог и трасса контролируемого запроса, затем выполнен `docker compose restart prometheus loki tempo grafana` +- **THEN** после готовности тот же лог по `request_id`, та же трасса по trace id и серии метрик API находятся снова + +### Requirement: Секрет Grafana вне Git + +Пароль администратора Grafana SHALL генерироваться локально в gitignored `secrets/` (`make secrets`) и передаваться контейнеру как compose secret через `GF_SECURITY_ADMIN_PASSWORD__FILE`; анонимный доступ и регистрация SHALL быть выключены. + +#### Scenario: Вход без пароля отклонён + +- **WHEN** клиент без учётных данных запрашивает `GET /api/search` Grafana +- **THEN** ответ `401` diff --git a/openspec/changes/add-lab6-telemetry-pipeline/tasks.md b/openspec/changes/add-lab6-telemetry-pipeline/tasks.md new file mode 100644 index 0000000..cd1f52c --- /dev/null +++ b/openspec/changes/add-lab6-telemetry-pipeline/tasks.md @@ -0,0 +1,38 @@ +## 1. Зависимости и платформа телеметрии + +- [ ] 1.1 Зависимости `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-http`, `opentelemetry-instrumentation-fastapi`, `opentelemetry-instrumentation-asyncpg`, `faststream[rabbit,otel]` в `pyproject.toml` и `uv.lock` +- [ ] 1.2 `PlatformSettings`: `otel_sdk_disabled`, `otel_exporter_otlp_endpoint`, `otel_service_name`, `telemetry_shutdown_seconds` +- [ ] 1.3 `shared/infrastructure/telemetry.py`: resource, sampler `ParentBased(ServerRoots)`, batch-экспорт трёх сигналов, View без метрик FastStream, `OtlpLogHandler`, инструментация asyncpg, ограниченный `shutdown`, `tag_request` +- [ ] 1.4 Журнал: `trace_id`/`span_id` в записи и в `PLATFORM_FIELDS`; `EventBus` выполняет отложенных подписчиков в контексте события +- [ ] 1.5 Проверка группы: unit-тесты — выключенный SDK не ставит провайдеры, запись с span несёт `trace_id`/`span_id`, OTLP-запись содержит только allowlist, подписчик получает контекст события + +## 2. Зона `attachments` + +- [ ] 2.1 Порт `JobObserver`, адаптер `OtelJobObserver` (counter, histogram с buckets, атрибуты и статус span), провайдер в `WorkerProvider` +- [ ] 2.2 Точка входа worker: длительность, исход, `job.processed` в журнал +- [ ] 2.3 Проверка группы: тест адаптера на `InMemoryMetricReader` и `InMemorySpanExporter` — labels `job.type`/`outcome`, атрибуты и `ERROR` для `failed` + +## 3. Сборка процессов + +- [ ] 3.1 `main.py`: телеметрия в `create_app`, FastAPI-инструментация без `/health/*` и внутренних spans, `messenger.request_id` из конвейера, остановка в lifespan +- [ ] 3.2 `worker.py`: телеметрия `messenger-worker`, `RabbitTelemetryMiddleware` на брокере, остановка после FastStream; `relay.py`: телеметрия `messenger-relay` +- [ ] 3.3 Проверка группы: тест server span и HTTP-метрики на `create_app` с in-memory провайдерами — шаблон маршрута, без `/health`, `messenger.request_id`; `make lint`, `make student-test` + +## 4. Стек наблюдаемости + +- [ ] 4.1 `infra/otel/collector.yaml`, `infra/prometheus/prometheus.yml` и recording rules, `infra/loki/loki.yaml`, `infra/tempo/tempo.yaml` из `.prep/lab6` +- [ ] 4.2 `infra/grafana/provisioning`, dashboards `messenger-api` и `messenger-pipeline` уровня «3» +- [ ] 4.3 `compose.yaml`: `healthtools`, `otel-collector`, `prometheus`, `loki`, `tempo`, `grafana`, volumes, секрет Grafana, сети `backend`/`edge`, переменные OTel у `api`, `relay`, `worker`; `.env.example` +- [ ] 4.4 `scripts/secrets-lab6.sh`, `scripts/obs-validate.sh`, `scripts/obs_check.py`; цели `secrets`, `obs-validate`, `telemetry-check`, `obs-evidence` +- [ ] 4.5 Проверка группы: `make obs-validate`, `docker compose config --quiet`, `make up` из чистого состояния — все сервисы `healthy`, порты наблюдаемости только на `127.0.0.1` + +## 5. Проверка на стенде + +- [ ] 5.1 `make test`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`, `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` для обеих реплик с `make restore`, `make level3` +- [ ] 5.2 `obs_check.py grafana`, `dashboards --strict`, `request`, `job`, `leaks`, cardinality, история после рестарта хранилищ, `make test` при остановленном Collector +- [ ] 5.3 Проверка группы: `make check`, `make validate`, `make lint`, `make student-test` + +## 6. Отчёт + +- [ ] 6.1 `evidence/`: стенд, smoke, persistence, failover, level3, obs-validate, grafana, dashboards, trace-request, trace-job, leaks, cardinality, telemetry-restart, student-tests, contract-checks +- [ ] 6.2 `REPORT.md`: шапка, запуск из чистого clone, архитектура и решения, роли, назначение хранилищ, соответствие сигналов и переменных, строки уровня «3», таблица отказов уровня «3»