From a41d6d39e884fae4bfe043852b1ef3e3e69f3d04 Mon Sep 17 00:00:00 2001 From: Artyom Date: Thu, 29 Oct 2026 04:37:41 +0300 Subject: [PATCH] Propose the telemetry pipeline as an openspec change Add the change add-lab6-telemetry-pipeline for level 3 of lab 6: every API worker process, the relay and the worker start the OpenTelemetry SDK after fork with service.name, service.version, a per-process service.instance.id and deployment.environment.name, export OTLP over HTTP with batch processors only, record HTTP server spans and the seconds histogram by route template, consumer spans and the jobs.processed counter and job.duration histogram by job type and outcome, PostgreSQL client spans inside requests and jobs, and send every allowlisted log record to Loki with trace_id and span_id. The stand gains the Collector, Prometheus, Loki, Tempo and Grafana with volumes and provisioning from Git, built from the verified .prep/lab6 configuration. The specs add lab6-service-telemetry and lab6-telemetry-stack and extend the unified log requirement of lab1-service-operability. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../.openspec.yaml | 2 + .../add-lab6-telemetry-pipeline/design.md | 70 ++++++++++ .../add-lab6-telemetry-pipeline/proposal.md | 31 +++++ .../specs/lab1-service-operability/spec.md | 20 +++ .../specs/lab6-service-telemetry/spec.md | 123 ++++++++++++++++++ .../specs/lab6-telemetry-stack/spec.md | 56 ++++++++ .../add-lab6-telemetry-pipeline/tasks.md | 38 ++++++ 7 files changed, 340 insertions(+) create mode 100644 openspec/changes/add-lab6-telemetry-pipeline/.openspec.yaml create mode 100644 openspec/changes/add-lab6-telemetry-pipeline/design.md create mode 100644 openspec/changes/add-lab6-telemetry-pipeline/proposal.md create mode 100644 openspec/changes/add-lab6-telemetry-pipeline/specs/lab1-service-operability/spec.md create mode 100644 openspec/changes/add-lab6-telemetry-pipeline/specs/lab6-service-telemetry/spec.md create mode 100644 openspec/changes/add-lab6-telemetry-pipeline/specs/lab6-telemetry-stack/spec.md create mode 100644 openspec/changes/add-lab6-telemetry-pipeline/tasks.md 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»