From 4f4e07a453909230909b3f8cad2f7e05bf04723b Mon Sep 17 00:00:00 2001 From: anastasia Date: Fri, 20 Nov 2026 14:34:40 +0300 Subject: [PATCH 1/2] feat: implement lab 6 observability and telemetry cost research --- .agents/skills/lab6-bench/SKILL.md | 34 + .agents/skills/messenger-stand/SKILL.md | 54 + .codex/rules/messenger.rules | 190 + .dockerignore | 14 + .env.example | 53 +- .gitignore | 11 + .python-version | 1 + AGENTS.md | 306 ++ Dockerfile | 65 + KNOWN_ISSUES.md | 153 + MR_COMMANDS.md | 42 + MR_DESCRIPTION.md | 68 + Makefile | 487 ++ REPORT.md | 685 ++- alembic.ini | 13 + bench/AGENTS.md | 300 ++ bench/RUNBOOK.md | 206 + bench/analysis.py | 546 +++ bench/bench.compose.yml | 188 + bench/bench.env | 11 + bench/common.py | 1168 +++++ bench/compare.py | 248 ++ bench/fill_objects.py | 119 + bench/loadgen.py | 1680 +++++++ bench/lookup.py | 212 + bench/otel/prometheus-lean.yml | 62 + bench/otel/tail-balanced.yaml | 45 + bench/otel/tail-typical.yaml | 35 + bench/plots.py | 412 ++ bench/queue.py | 1482 +++++++ bench/reconcile.py | 952 ++++ bench/run.py | 3917 +++++++++++++++++ bench/sampler.py | 274 ++ bench/telemetry.py | 1480 +++++++ bench/uploads.py | 583 +++ compose.yaml | 738 ++++ evidence/AGENTS.md | 65 + evidence/alerts/alerts-check.txt | 43 + evidence/alerts/promtool.txt | 18 + evidence/attachments/defense.txt | 47 + evidence/s3/privacy.txt | 80 + evidence/stand/stand.txt | 53 + .../baseline-after-restart/classes.csv | 241 + .../baseline-after-restart/meta.json | 1900 ++++++++ .../raw/balanced-r1-find.json | 2114 +++++++++ .../raw/balanced-r1-mix.csv.gz | Bin 0 -> 408610 bytes .../raw/balanced-r1-snaps.json | 324 ++ .../raw/balanced-r2-find.json | 2104 +++++++++ .../raw/balanced-r2-mix.csv.gz | Bin 0 -> 406674 bytes .../raw/balanced-r2-snaps.json | 324 ++ .../raw/balanced-r3-find.json | 2144 +++++++++ .../raw/balanced-r3-mix.csv.gz | Bin 0 -> 410510 bytes .../raw/balanced-r3-snaps.json | 329 ++ .../raw/full-r1-find.json | 2134 +++++++++ .../raw/full-r1-mix.csv.gz | Bin 0 -> 405861 bytes .../raw/full-r1-snaps.json | 290 ++ .../raw/full-r2-find.json | 2114 +++++++++ .../raw/full-r2-mix.csv.gz | Bin 0 -> 409894 bytes .../raw/full-r2-snaps.json | 290 ++ .../raw/full-r3-find.json | 2124 +++++++++ .../raw/full-r3-mix.csv.gz | Bin 0 -> 409385 bytes .../raw/full-r3-snaps.json | 290 ++ .../raw/head-r1-find.json | 2114 +++++++++ .../raw/head-r1-mix.csv.gz | Bin 0 -> 408381 bytes .../raw/head-r1-snaps.json | 287 ++ .../raw/head-r2-find.json | 2144 +++++++++ .../raw/head-r2-mix.csv.gz | Bin 0 -> 405919 bytes .../raw/head-r2-snaps.json | 287 ++ .../raw/head-r3-find.json | 2114 +++++++++ .../raw/head-r3-mix.csv.gz | Bin 0 -> 408090 bytes .../raw/head-r3-snaps.json | 290 ++ .../raw/off-r1-mix.csv.gz | Bin 0 -> 404340 bytes .../raw/off-r2-mix.csv.gz | Bin 0 -> 408667 bytes .../raw/off-r3-mix.csv.gz | Bin 0 -> 408647 bytes .../raw/sampler-r1.jsonl.gz | Bin 0 -> 154626 bytes .../raw/sampler-r2.jsonl.gz | Bin 0 -> 154585 bytes .../raw/sampler-r3.jsonl.gz | Bin 0 -> 155593 bytes .../raw/tail-r1-find.json | 2134 +++++++++ .../raw/tail-r1-mix.csv.gz | Bin 0 -> 406337 bytes .../raw/tail-r1-snaps.json | 326 ++ .../raw/tail-r2-find.json | 2124 +++++++++ .../raw/tail-r2-mix.csv.gz | Bin 0 -> 405266 bytes .../raw/tail-r2-snaps.json | 326 ++ .../raw/tail-r3-find.json | 2124 +++++++++ .../raw/tail-r3-mix.csv.gz | Bin 0 -> 408613 bytes .../raw/tail-r3-snaps.json | 326 ++ .../baseline-after-restart/runs.csv | 16 + .../baseline-after-restart/summary.md | 75 + evidence/telemetry-cost/baseline/classes.csv | 33 + evidence/telemetry-cost/baseline/meta.json | 680 +++ .../baseline/raw/balanced-r1-find.json | 2144 +++++++++ .../baseline/raw/balanced-r1-mix.csv.gz | Bin 0 -> 406500 bytes .../baseline/raw/balanced-r1-snaps.json | 324 ++ .../baseline/raw/head-r1-find.json | 2104 +++++++++ .../baseline/raw/head-r1-mix.csv.gz | Bin 0 -> 407384 bytes .../baseline/raw/head-r1-snaps.json | 287 ++ evidence/telemetry-cost/baseline/runs.csv | 3 + evidence/telemetry-cost/baseline/summary.md | 66 + evidence/telemetry/check.txt | 43 + evidence/telemetry/outage.txt | 25 + evidence/telemetry/trace-chain.txt | 52 + evidence/tests/failure-checks.txt | 79 + evidence/tests/final-check-20261116.txt | 30 + evidence/tests/host-preflight-20261116.txt | 57 + evidence/tests/host-stand-20261116.txt | 60 + evidence/tests/test-isolated.txt | 70 + evidence/tests/test.txt | 13 + infra/AGENTS.md | 181 + infra/haproxy/haproxy.cfg | 153 + infra/otel/collector.yaml | 108 + infra/otel/grafana/dashboards.yaml | 17 + .../grafana/dashboards/messenger-lab6.json | 414 ++ infra/otel/grafana/datasources.yaml | 56 + infra/otel/loki/loki.yaml | 48 + infra/otel/prometheus/prometheus.yml | 36 + infra/otel/prometheus/rules.test.yml | 104 + infra/otel/prometheus/rules.yml | 86 + infra/otel/runbooks/high-error-rate.md | 38 + infra/otel/runbooks/queue-lag.md | 36 + infra/otel/runbooks/telemetry-down.md | 27 + infra/otel/tempo/tempo.yaml | 39 + infra/rabbitmq/rabbitmq.conf | 10 + infra/s3/bootstrap.sh | 408 ++ infra/valkey/valkey.conf | 15 + migrations/AGENTS.md | 109 + migrations/env.py | 82 + migrations/script.py.mako | 25 + migrations/versions/0001_messenger_schema.py | 147 + migrations/versions/0002_idempotency_keys.py | 81 + migrations/versions/0003_attachments.py | 169 + migrations/versions/0004_attachment_jobs.py | 222 + migrations/versions/0005_job_trace_context.py | 38 + pyproject.toml | 78 + requirements.txt | 538 +++ scripts/lab6.py | 1866 ++++++++ scripts/restart.sh | 20 + scripts/rolling-update.sh | 428 ++ scripts/stop-one.sh | 83 + src/AGENTS.md | 290 ++ src/__init__.py | 7 + src/__main__.py | 10 + src/api/AGENTS.md | 185 + src/api/__init__.py | 0 src/api/deps.py | 195 + src/api/handlers.py | 130 + src/api/identity.py | 89 + src/api/request_id.py | 85 + src/api/routes/__init__.py | 26 + src/api/routes/attachments.py | 161 + src/api/routes/chats.py | 46 + src/api/routes/health.py | 32 + src/api/routes/messages.py | 52 + src/api/routes/sessions.py | 29 + src/api/routes/users.py | 24 + src/api/schemas.py | 214 + src/api/tracing.py | 104 + src/broker.py | 332 ++ src/cache.py | 129 + src/cleaner/__init__.py | 1 + src/cleaner/__main__.py | 10 + src/cleaner/main.py | 313 ++ src/clock.py | 51 + src/config.py | 708 +++ src/constants.py | 148 + src/db.py | 226 + src/domain.py | 190 + src/early_stop.py | 63 + src/errors.py | 200 + src/healthcheck.py | 25 + src/images.py | 392 ++ src/log.py | 167 + src/main.py | 221 + src/pagination.py | 88 + src/passwords.py | 75 + src/relay/__init__.py | 0 src/relay/__main__.py | 9 + src/relay/main.py | 269 ++ src/renderer.py | 177 + src/s3.py | 380 ++ src/services/AGENTS.md | 205 + src/services/__init__.py | 17 + src/services/access.py | 21 + src/services/attachments.py | 419 ++ src/services/chats.py | 56 + src/services/cleanup.py | 225 + src/services/messages.py | 109 + src/services/processing.py | 239 + src/services/reconcile.py | 720 +++ src/services/relay.py | 109 + src/services/replay.py | 59 + src/services/sessions.py | 94 + src/services/users.py | 30 + src/storage/AGENTS.md | 182 + src/storage/__init__.py | 15 + src/storage/base.py | 391 ++ src/storage/cached.py | 223 + src/storage/objects.py | 148 + src/storage/pipeline.py | 512 +++ src/storage/postgres.py | 892 ++++ src/storage/tables.py | 477 ++ src/telemetry/__init__.py | 315 ++ src/telemetry/sdk.py | 467 ++ src/uploads.py | 63 + src/worker/__init__.py | 0 src/worker/__main__.py | 9 + src/worker/main.py | 311 ++ src/worker/render.py | 176 + student-tests/AGENTS.md | 158 + student-tests/conftest.py | 153 + student-tests/fault_hook.py | 708 +++ student-tests/fixtures/sample.jpg | Bin 0 -> 8804 bytes student-tests/helpers.py | 402 ++ student-tests/images.py | 160 + student-tests/stand.compose.yml | 33 + student-tests/stand.env | 13 + student-tests/stand.py | 521 +++ student-tests/test_attachments.py | 462 ++ student-tests/test_auth.py | 196 + student-tests/test_balancing.py | 77 + student-tests/test_cache.py | 61 + student-tests/test_failures.py | 769 ++++ student-tests/test_idempotency.py | 252 ++ student-tests/test_pipeline.py | 350 ++ student-tests/test_processing.py | 194 + student-tests/test_race.py | 214 + student-tests/test_request_id.py | 86 + student-tests/test_rubric.py | 228 + student-tests/unit/test_telemetry.py | 453 ++ student-tests/unit/test_trace_chain.py | 170 + tools/audit_incidents.py | 160 + tools/docker-compat/docker | 16 + tools/docker-compat/setup.sh | 31 + uv.lock | 1257 ++++++ 233 files changed, 79726 insertions(+), 16 deletions(-) create mode 100644 .agents/skills/lab6-bench/SKILL.md create mode 100644 .agents/skills/messenger-stand/SKILL.md create mode 100644 .codex/rules/messenger.rules create mode 100644 .python-version create mode 100644 AGENTS.md create mode 100644 Dockerfile create mode 100644 KNOWN_ISSUES.md create mode 100644 MR_COMMANDS.md create mode 100644 MR_DESCRIPTION.md create mode 100644 alembic.ini create mode 100644 bench/AGENTS.md create mode 100644 bench/RUNBOOK.md create mode 100644 bench/analysis.py create mode 100644 bench/bench.compose.yml create mode 100644 bench/bench.env create mode 100644 bench/common.py create mode 100644 bench/compare.py create mode 100644 bench/fill_objects.py create mode 100644 bench/loadgen.py create mode 100644 bench/lookup.py create mode 100644 bench/otel/prometheus-lean.yml create mode 100644 bench/otel/tail-balanced.yaml create mode 100644 bench/otel/tail-typical.yaml create mode 100644 bench/plots.py create mode 100644 bench/queue.py create mode 100644 bench/reconcile.py create mode 100644 bench/run.py create mode 100644 bench/sampler.py create mode 100644 bench/telemetry.py create mode 100644 bench/uploads.py create mode 100644 compose.yaml create mode 100644 evidence/AGENTS.md create mode 100644 evidence/alerts/alerts-check.txt create mode 100644 evidence/alerts/promtool.txt create mode 100644 evidence/attachments/defense.txt create mode 100644 evidence/s3/privacy.txt create mode 100644 evidence/stand/stand.txt create mode 100644 evidence/telemetry-cost/baseline-after-restart/classes.csv create mode 100644 evidence/telemetry-cost/baseline-after-restart/meta.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/balanced-r1-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/balanced-r1-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/balanced-r1-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/balanced-r2-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/balanced-r2-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/balanced-r2-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/balanced-r3-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/balanced-r3-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/balanced-r3-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/full-r1-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/full-r1-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/full-r1-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/full-r2-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/full-r2-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/full-r2-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/full-r3-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/full-r3-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/full-r3-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/head-r1-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/head-r1-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/head-r1-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/head-r2-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/head-r2-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/head-r2-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/head-r3-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/head-r3-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/head-r3-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/off-r1-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/off-r2-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/off-r3-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/sampler-r1.jsonl.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/sampler-r2.jsonl.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/sampler-r3.jsonl.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/tail-r1-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/tail-r1-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/tail-r1-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/tail-r2-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/tail-r2-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/tail-r2-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/tail-r3-find.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/tail-r3-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline-after-restart/raw/tail-r3-snaps.json create mode 100644 evidence/telemetry-cost/baseline-after-restart/runs.csv create mode 100644 evidence/telemetry-cost/baseline-after-restart/summary.md create mode 100644 evidence/telemetry-cost/baseline/classes.csv create mode 100644 evidence/telemetry-cost/baseline/meta.json create mode 100644 evidence/telemetry-cost/baseline/raw/balanced-r1-find.json create mode 100644 evidence/telemetry-cost/baseline/raw/balanced-r1-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline/raw/balanced-r1-snaps.json create mode 100644 evidence/telemetry-cost/baseline/raw/head-r1-find.json create mode 100644 evidence/telemetry-cost/baseline/raw/head-r1-mix.csv.gz create mode 100644 evidence/telemetry-cost/baseline/raw/head-r1-snaps.json create mode 100644 evidence/telemetry-cost/baseline/runs.csv create mode 100644 evidence/telemetry-cost/baseline/summary.md create mode 100644 evidence/telemetry/check.txt create mode 100644 evidence/telemetry/outage.txt create mode 100644 evidence/telemetry/trace-chain.txt create mode 100644 evidence/tests/failure-checks.txt create mode 100644 evidence/tests/final-check-20261116.txt create mode 100644 evidence/tests/host-preflight-20261116.txt create mode 100644 evidence/tests/host-stand-20261116.txt create mode 100644 evidence/tests/test-isolated.txt create mode 100644 evidence/tests/test.txt create mode 100644 infra/AGENTS.md create mode 100644 infra/haproxy/haproxy.cfg create mode 100644 infra/otel/collector.yaml create mode 100644 infra/otel/grafana/dashboards.yaml create mode 100644 infra/otel/grafana/dashboards/messenger-lab6.json create mode 100644 infra/otel/grafana/datasources.yaml create mode 100644 infra/otel/loki/loki.yaml create mode 100644 infra/otel/prometheus/prometheus.yml create mode 100644 infra/otel/prometheus/rules.test.yml create mode 100644 infra/otel/prometheus/rules.yml create mode 100644 infra/otel/runbooks/high-error-rate.md create mode 100644 infra/otel/runbooks/queue-lag.md create mode 100644 infra/otel/runbooks/telemetry-down.md create mode 100644 infra/otel/tempo/tempo.yaml create mode 100644 infra/rabbitmq/rabbitmq.conf create mode 100755 infra/s3/bootstrap.sh create mode 100644 infra/valkey/valkey.conf create mode 100644 migrations/AGENTS.md create mode 100644 migrations/env.py create mode 100644 migrations/script.py.mako create mode 100644 migrations/versions/0001_messenger_schema.py create mode 100644 migrations/versions/0002_idempotency_keys.py create mode 100644 migrations/versions/0003_attachments.py create mode 100644 migrations/versions/0004_attachment_jobs.py create mode 100644 migrations/versions/0005_job_trace_context.py create mode 100644 pyproject.toml create mode 100644 requirements.txt create mode 100755 scripts/lab6.py create mode 100755 scripts/restart.sh create mode 100755 scripts/rolling-update.sh create mode 100755 scripts/stop-one.sh create mode 100644 src/AGENTS.md create mode 100644 src/__init__.py create mode 100644 src/__main__.py create mode 100644 src/api/AGENTS.md create mode 100644 src/api/__init__.py create mode 100644 src/api/deps.py create mode 100644 src/api/handlers.py create mode 100644 src/api/identity.py create mode 100644 src/api/request_id.py create mode 100644 src/api/routes/__init__.py create mode 100644 src/api/routes/attachments.py create mode 100644 src/api/routes/chats.py create mode 100644 src/api/routes/health.py create mode 100644 src/api/routes/messages.py create mode 100644 src/api/routes/sessions.py create mode 100644 src/api/routes/users.py create mode 100644 src/api/schemas.py create mode 100644 src/api/tracing.py create mode 100644 src/broker.py create mode 100644 src/cache.py create mode 100644 src/cleaner/__init__.py create mode 100644 src/cleaner/__main__.py create mode 100644 src/cleaner/main.py create mode 100644 src/clock.py create mode 100644 src/config.py create mode 100644 src/constants.py create mode 100644 src/db.py create mode 100644 src/domain.py create mode 100644 src/early_stop.py create mode 100644 src/errors.py create mode 100644 src/healthcheck.py create mode 100644 src/images.py create mode 100644 src/log.py create mode 100644 src/main.py create mode 100644 src/pagination.py create mode 100644 src/passwords.py create mode 100644 src/relay/__init__.py create mode 100644 src/relay/__main__.py create mode 100644 src/relay/main.py create mode 100644 src/renderer.py create mode 100644 src/s3.py create mode 100644 src/services/AGENTS.md create mode 100644 src/services/__init__.py create mode 100644 src/services/access.py create mode 100644 src/services/attachments.py create mode 100644 src/services/chats.py create mode 100644 src/services/cleanup.py create mode 100644 src/services/messages.py create mode 100644 src/services/processing.py create mode 100644 src/services/reconcile.py create mode 100644 src/services/relay.py create mode 100644 src/services/replay.py create mode 100644 src/services/sessions.py create mode 100644 src/services/users.py create mode 100644 src/storage/AGENTS.md create mode 100644 src/storage/__init__.py create mode 100644 src/storage/base.py create mode 100644 src/storage/cached.py create mode 100644 src/storage/objects.py create mode 100644 src/storage/pipeline.py create mode 100644 src/storage/postgres.py create mode 100644 src/storage/tables.py create mode 100644 src/telemetry/__init__.py create mode 100644 src/telemetry/sdk.py create mode 100644 src/uploads.py create mode 100644 src/worker/__init__.py create mode 100644 src/worker/__main__.py create mode 100644 src/worker/main.py create mode 100644 src/worker/render.py create mode 100644 student-tests/AGENTS.md create mode 100644 student-tests/conftest.py create mode 100755 student-tests/fault_hook.py create mode 100644 student-tests/fixtures/sample.jpg create mode 100644 student-tests/helpers.py create mode 100644 student-tests/images.py create mode 100644 student-tests/stand.compose.yml create mode 100644 student-tests/stand.env create mode 100644 student-tests/stand.py create mode 100644 student-tests/test_attachments.py create mode 100644 student-tests/test_auth.py create mode 100644 student-tests/test_balancing.py create mode 100644 student-tests/test_cache.py create mode 100644 student-tests/test_failures.py create mode 100644 student-tests/test_idempotency.py create mode 100644 student-tests/test_pipeline.py create mode 100644 student-tests/test_processing.py create mode 100644 student-tests/test_race.py create mode 100644 student-tests/test_request_id.py create mode 100644 student-tests/test_rubric.py create mode 100644 student-tests/unit/test_telemetry.py create mode 100644 student-tests/unit/test_trace_chain.py create mode 100644 tools/audit_incidents.py create mode 100755 tools/docker-compat/docker create mode 100644 tools/docker-compat/setup.sh create mode 100644 uv.lock diff --git a/.agents/skills/lab6-bench/SKILL.md b/.agents/skills/lab6-bench/SKILL.md new file mode 100644 index 0000000..f749d9f --- /dev/null +++ b/.agents/skills/lab6-bench/SKILL.md @@ -0,0 +1,34 @@ +--- +name: lab6-bench +description: Load measurements of lab 6 for grade 5, track 1 "cost of observability" — telemetry off/full, head sampling, typical and balanced tail sampling with metric aggregation (profile telemetry) under one open load with rare events of known count; latency, replica CPU per request, container CPU/RAM, ingest of Collector/Tempo/Loki/Prometheus, telemetry losses, which errors and slow requests the sampling keeps. Use when asked to run benchmarks, make bench-telemetry (or bench-telemetry-quick), or fill REPORT.md with measured numbers and the outcomes of hypotheses T1–T7 and criteria S1–S5. +--- + +# Замеры лабы 6 (трек 1) + +Сначала прочитай целиком (`cat`): **`bench/RUNBOOK.md`** (порядок шагов), +`bench/AGENTS.md` (правила стенда), корневой `AGENTS.md` (разделы 2, +8–11 действуют всегда), в `REPORT.md` — раздел «Трек 1. Цена +наблюдаемости» (гипотезы и пороги записаны до замеров). + +Коротко: + +1. Шаг 0 RUNBOOK: ресурсы ВМ Docker (≥ 10 CPU, ≥ 7,7 ГиБ), самопроверки + разбора (`bench/telemetry.py --selftest` и остальные), `make up`, + `make test`, `make telemetry-check`, `make test-isolated`, `make + failure-checks`, `make stop`, самопроверка `make bench-telemetry-quick` + (~7 мин). Остановка и отчёт пользователю. +2. Шаг 1: `make bench-telemetry` (~50 мин) → `evidence/telemetry-cost/baseline/`; + таблицы и итоги T1–T7, S1–S5 из `summary.md` — в `REPORT.md` (строки + `TODO (Codex)`). Остановка и отчёт. +3. Шаг 2: `make lint`, `make check`, `make test-isolated`, абзац + «Состояние» в `AGENTS.md`, уборка `vlad-bench*`. + +Нельзя: переписывать гипотезы, пороги и критерии после замеров, менять +код приложения, профиль или слои `bench/otel/` ради результата, править +файлы меток руками, перезаписывать или удалять каталоги меток без +согласия, считать числа вручную вместо `summary.md`, переводить рабочий +стенд на `balanced`. Если `balanced` не прошёл — правило из `REPORT.md`, +новая метка только с согласия пользователя. Долгое — в фоне с журналом +(`nohup make … > /tmp/bench-*.log 2>&1 &`), docker — вне sandbox с +одобрения пользователя. `aborted`, `host_warnings`, `not_applied`, +упавшие проверки — остановиться и сказать пользователю. diff --git a/.agents/skills/messenger-stand/SKILL.md b/.agents/skills/messenger-stand/SKILL.md new file mode 100644 index 0000000..09b3228 --- /dev/null +++ b/.agents/skills/messenger-stand/SKILL.md @@ -0,0 +1,54 @@ +--- +name: messenger-stand +description: Run, check and operate the lab 6 messenger stand — HAProxy with API replicas, PostgreSQL, Valkey, SeaweedFS S3, RabbitMQ, relay, image worker, cleaner, plus the telemetry stack (OTel Collector, Prometheus, Loki, Tempo, Grafana). Use when asked to start or stop the stand, run make test / student-test / test-isolated / failure-checks / s3-check, telemetry-check / trace-chain / alerts-test / alerts-check / telemetry-outage, open Grafana, show the defense scenario (worker stopped → 202 → restart → ready, firing → resolved), inspect the pipeline state, list or replay failed jobs, stop one replica, run cleanup or reconcile, do a rolling update, or reproduce an API bug over HTTP. +--- + +# Стенд мессенджера лабы 6 + +Команды — корневой `AGENTS.md`, раздел 4; устройство стенда, брокер, S3, +worker, телеметрия, таймауты, скрипты — `infra/AGENTS.md`; pipeline — +`src/services/AGENTS.md`; тесты — `student-tests/AGENTS.md`. + +| Задача | Команда | +|---|---| +| поднять стенд целиком | `make up` → `127.0.0.1:${HOST_PORT:-8180}` | +| адрес Grafana и dashboard | `make grafana` (порт `GRAFANA_HOST_PORT`, 3180) | +| связь трасса ↔ лог, метрики, утечки | `make telemetry-check` | +| одна трасса API → relay → worker с retry | `make trace-chain` | +| правила Prometheus: promtool check и test | `make alerts-test` | +| alerts firing → resolved на реальных отказах (~6,5 мин) | `make alerts-check` | +| Tempo недоступен под нагрузкой | `make telemetry-outage [OUTAGE_SECONDS=120]` | +| журнал Collector, Prometheus, Loki, Tempo, Grafana | `make logs-telemetry` | +| публичный smoke / свои тесты | `make test`, `make student-test` | +| всё на чистом отдельном стенде | `make test-isolated` | +| проверки отказов (в том числе pipeline) | `make failure-checks [FAULT_ARGS=-rP]` | +| сценарий защиты, шаги 2–3 | `make defense` | +| задания по состояниям и очередь брокера | `make pipeline-state` | +| реестр failed / возврат | `make replay [ERROR_CODE=…]` / `make replay APPLY=1 ATTACHMENT= OPERATOR=<кто> REASON=<зачем>` | +| остановить / запустить worker | `make stop-worker` / `make start-worker` | +| журнал relay и worker | `make logs-pipeline` | +| приватность bucket вне API | `make s3-check` | +| вложение после остановки принявшей реплики | `make attachment-failover [STOP_MODE=kill]` | +| реплики за LB | `make instances`, `make lb-stats`, `make failover-each` | +| уборка / сверка (dry-run) | `make cleanup-once` / `make reconcile [STRATEGY=head] [DEEP=1]` | +| обновить код без простоя | `make rolling-update` | +| остановить / удалить контейнеры | `make stop` / `make down` (volume остаются) | + +Правила: + +- Порт занят другим сервисом — не убивать процесс: другие порты в `.env` + (`make env HOST_PORT=… POSTGRES_HOST_PORT=… VALKEY_HOST_PORT=… + S3_HOST_PORT=… BROKER_HOST_PORT=… GRAFANA_HOST_PORT=…` до первого `make up`) и + `BASE_URL=http://localhost:<порт>` у тестов и `make defense`. +- `make defense` останавливает worker и перезапускает хранилища и брокер + рабочего стенда (`scripts/restart.sh`); worker запускается при любом + исходе. +- `make alerts-check` останавливает worker и блокирует таблицу `sessions` + на рабочем стенде, `make telemetry-outage` — останавливает Tempo; оба + возвращают сервис при любом исходе, запускать с согласия пользователя. +- `make replay APPLY=1` и `make reconcile APPLY=1` меняют рабочий стенд — + только с согласия пользователя; без `APPLY` — только показ. +- `make wipe`, `docker compose down -v` и любое удаление volume — только + с согласия пользователя. +- Пароли, ключи S3 и брокера из `.env`, токены не печатать; в + `evidence/` — только обезличенный вывод (`evidence/AGENTS.md`). diff --git a/.codex/rules/messenger.rules b/.codex/rules/messenger.rules new file mode 100644 index 0000000..01cc0d7 --- /dev/null +++ b/.codex/rules/messenger.rules @@ -0,0 +1,190 @@ +# Правила команд Codex для проекта (execpolicy, Starlark). +# +# Действуют на команды, которые Codex запускает вне sandbox (docker, сеть): +# allow — без вопроса; +# prompt — спросить пользователя перед каждым запуском; +# forbidden — не запускать никогда. +# Несколько совпавших правил — побеждает самое строгое (forbidden → +# prompt → allow). pattern — точный префикс аргументов команды; список в +# позиции — варианты. match / not_match — примеры, которые Codex +# проверяет при загрузке правил. +# +# Файл загружается, только если проект доверенный (слой .codex/ проекта +# trusted). После правки — перезапустить Codex. Проверка правила (команда — +# без «--» перед ней: с ним ничего не сопоставляется): +# codex execpolicy check --pretty --rules "$PWD/.codex/rules/messenger.rules" git push +# +# Источник запретов — корневой AGENTS.md, раздел 2 «Нельзя»; правила их +# дублируют на уровне команд, но не заменяют. + +# --- git: только смотреть; изменения — по просьбе пользователя ------------- + +prefix_rule( + pattern = ["git", ["status", "diff", "log", "show", "rev-parse", "ls-files"]], + decision = "allow", + justification = "Read-only git commands are always fine.", + match = ["git status", "git diff --stat", "git log --oneline -5"], + not_match = ["git commit -m x"], +) + +prefix_rule( + pattern = ["git", ["commit", "checkout", "switch", "reset", "stash", "rebase", "merge", "restore", "tag", "branch"]], + decision = "prompt", + justification = "AGENTS.md: git changes only when the user asked for them (commit message in English, conventional style).", + match = ["git commit -m 'feat: x'", "git reset --hard", "git checkout main"], + not_match = ["git status"], +) + +prefix_rule( + pattern = ["git", ["push", "clean"]], + decision = "forbidden", + justification = "Never push or clean the working tree: the user does it; git clean would delete evidence and local files.", + match = ["git push", "git push origin main", "git clean -fdx"], +) + +# --- данные стендов: удаление только с согласия ----------------------------- + +prefix_rule( + pattern = ["make", "wipe"], + decision = "prompt", + justification = "make wipe deletes the working stand volume (all data). Ask the user first (AGENTS.md, section 2, item 8).", + match = ["make wipe"], +) + +prefix_rule( + pattern = ["docker", "compose", "down", "-v"], + decision = "prompt", + justification = "down -v deletes volumes. The bench and test stands remove their own projects themselves; for the working stand ask the user.", + match = ["docker compose down -v", "docker compose down -v --remove-orphans"], + not_match = ["docker compose down"], +) + +prefix_rule( + pattern = ["docker", "volume", ["rm", "prune"]], + decision = "prompt", + justification = "Deleting volumes deletes data: only bench leftovers (vlad-bench*) and only with the user's consent.", + match = ["docker volume rm vlad-bench_pgdata", "docker volume prune -f"], +) + +prefix_rule( + pattern = ["docker", ["rm", "kill", "stop", "pause"]], + decision = "prompt", + justification = "Only own containers (vladimirceva-lab6*, vlad-bench*); never containers of other projects.", + match = ["docker rm -f vlad-bench-gen", "docker stop some-container"], +) + +prefix_rule( + pattern = ["docker", ["system", "builder", "image", "container", "network"], "prune"], + decision = "forbidden", + justification = "Prune touches every project on this machine. Remove own leftovers by name instead (bench/AGENTS.md).", + match = ["docker system prune -af", "docker image prune -a"], +) + +# --- процессы: не убивать по порту вслепую ------------------------------------ + +prefix_rule( + pattern = [["kill", "pkill", "killall"]], + decision = "prompt", + justification = "Kill only a PID whose command is `python -m src` (AGENTS.md, section 10). A published port on macOS belongs to com.docker.backend: killing it stops Docker Desktop.", + match = ["kill 12345", "pkill -f uvicorn"], +) + +prefix_rule( + pattern = ["rm", ["-rf", "-fr", "-r"]], + decision = "prompt", + justification = "Recursive delete: label folders in evidence/ are removed only with the user's consent (bench/AGENTS.md).", + match = ["rm -rf evidence/scaling/quick-x"], +) + +# --- проект: проверки, стенд, замеры — без вопроса ---------------------------- + +prefix_rule( + pattern = [ + "make", + [ + "install", "lint", "fmt", "check", "validate", "test", "load", + "test-persistence", "test-failover", "student-test", "test-isolated", + "failure-checks", "requirements", "requirements-check", "env", + "docker-build", "up", "stop", "down", "logs", "db-up", "run", + "migrate-local", "replicas", "instances", "lb-stats", + "failover-each", "rolling-update", + "attachment-failover", "s3-check", "cleanup-once", + "stop-worker", "start-worker", "defense", "pipeline-state", + "logs-pipeline", "run-relay", "run-worker", + "unit-test", "grafana", "logs-telemetry", "telemetry-check", + "trace-chain", "alerts-test", "alerts-check", "telemetry-outage", + "bench-telemetry", "bench-telemetry-quick", + "bench-queue", "bench-queue-quick", + "bench-uploads", "bench-uploads-quick", "bench-reconcile", + "bench-reconcile-quick", + "bench-failover", "bench-failover-quick", "bench-rollout", + "bench-rollout-quick", "bench-scaling", "bench-scaling-quick", + "bench-compare", "bench-plots", + ], + ], + decision = "allow", + justification = "Project targets: checks, the working stand without deleting data, bench profiles (bench/RUNBOOK.md).", + match = ["make lint", "make test-isolated", "make bench-telemetry", "make bench-telemetry-quick", "make telemetry-check", "make failover-each STOP_MODE=kill"], + not_match = ["make wipe", "make reconcile APPLY=1", "make replay APPLY=1"], +) + +# реестр failed: показ ничего не меняет +prefix_rule( + pattern = ["make", "replay"], + decision = "allow", + justification = "Without APPLY=1 replay only lists failed jobs.", + match = ["make replay", "make replay ERROR_CODE=retry_exhausted"], +) + +# возврат failed в очередь меняет рабочую базу: спросить пользователя +prefix_rule( + pattern = ["make", "replay", "APPLY=1"], + decision = "prompt", + justification = "replay --apply returns failed jobs to the queue of the working stand and writes an audit row: ask the user first.", + match = ["make replay APPLY=1 ATTACHMENT=x OPERATOR=me REASON=s3"], +) + +# make reconcile без APPLY — dry-run: ничего не меняет +prefix_rule( + pattern = ["make", "reconcile"], + decision = "allow", + justification = "Dry-run reconcile only reports discrepancies (exit 0 or 3).", + match = ["make reconcile", "make reconcile STRATEGY=head DEEP=1"], +) + +# с APPLY=1 сверка удаляет объекты без строки и помечает потерянные +# оригиналы в рабочей базе: спросить пользователя +prefix_rule( + pattern = ["make", "reconcile", "APPLY=1"], + decision = "prompt", + justification = "reconcile --apply deletes orphan objects and marks lost originals in the working stand: ask the user first.", + match = ["make reconcile APPLY=1", "make reconcile APPLY=1 MAX_CHANGES=10"], +) + +prefix_rule( + pattern = ["docker", ["ps", "info", "version", "inspect", "logs", "images", "events", "exec", "cp", "build", "tag", "run", "start", "unpause"]], + decision = "allow", + justification = "Inspecting and running own stand containers; deletion is covered by stricter rules above.", + match = ["docker ps -a", "docker info", "docker logs -t vlad-bench-lb"], +) + +prefix_rule( + pattern = ["docker", "compose"], + decision = "allow", + justification = "Compose of this project; down -v is prompted by the stricter rule above.", + match = ["docker compose ps", "docker compose logs api"], +) + +prefix_rule( + pattern = ["uv", ["run", "sync", "lock", "export"]], + decision = "allow", + justification = "Project environment from uv.lock; new dependencies still need the user's consent (AGENTS.md, section 2, item 11).", + match = ["uv run pytest", "uv sync", "uv run python bench/telemetry.py --selftest"], +) + +prefix_rule( + pattern = [["python3", "python"], ["scripts/lab6.py", "student-tests/stand.py", "tests/smoke.py", "tests/resilience.py", "scripts/check_contract.py"]], + decision = "allow", + justification = "Project scripts on the host Python (stdlib only).", + match = ["python3 scripts/lab6.py s3-check", "python3 student-tests/stand.py isolated"], +) diff --git a/.dockerignore b/.dockerignore index bc16e55..75be601 100644 --- a/.dockerignore +++ b/.dockerignore @@ -18,3 +18,17 @@ __pycache__ node_modules evidence .DS_Store +.codex +.agents +tests +student-tests +bench +contracts +infra +scripts +**/AGENTS.md +**/__pycache__ +**/*.pyc +**/.DS_Store +*.md +**/*.md diff --git a/.env.example b/.env.example index 2b32655..8ba4208 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,7 @@ # Copy to .env for your LOCAL synthetic test environment; never commit .env. # These are logical interface suggestions; map actual framework names in REPORT.md. -APP_HOST=0.0.0.0 +# Host process (make run); the container binds 0.0.0.0 in Dockerfile. +APP_HOST=127.0.0.1 APP_PORT=8080 APP_ENV=lab SESSION_TTL_SECONDS=3600 @@ -11,6 +12,8 @@ SESSION_STORE=postgres CACHE_URL_FILE=/run/secrets/cache_url API_REPLICAS=2 IDEMPOTENCY_TTL_SECONDS=86400 +# Lab 4 logical names (skeleton). Containers get S3_ENDPOINT from compose.yaml, +# make run overrides it with 127.0.0.1:S3_HOST_PORT; keys come from the lines below. S3_ENDPOINT=http://s3:9000 S3_REGION=us-east-1 S3_BUCKET=messenger-attachments @@ -18,13 +21,61 @@ S3_ACCESS_KEY_ID_FILE=/run/secrets/s3_access_key_id S3_SECRET_ACCESS_KEY_FILE=/run/secrets/s3_secret_access_key MAX_UPLOAD_BYTES=10485760 MAX_IMAGE_PIXELS=40000000 +# Lab 5 logical names (skeleton). BROKER_URL_FILE is not used: relay and worker +# get BROKER_HOST/BROKER_PASSWORD from compose.yaml (REPORT.md, «Конфигурация»). BROKER_URL_FILE=/run/secrets/broker_url WORKER_CONCURRENCY=2 JOB_MAX_ATTEMPTS=5 JOB_TIMEOUT_SECONDS=60 STAGING_RETENTION_SECONDS=86400 +# Lab 6 names (skeleton). service.name is fixed by each entry point +# (messenger-api, messenger-worker, messenger-relay), so OTEL_SERVICE_NAME is +# not read; compose.yaml points api, worker and relay at the Collector by name. +# Only deployment.environment.name is accepted in OTEL_RESOURCE_ATTRIBUTES. +# make run sets OTEL_SDK_DISABLED=true for host processes. OTEL_SERVICE_NAME=messenger-api # Worker must set a distinct service.name. OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=lab + +# Compose and make run. make env fills the empty passwords and keys locally. +HOST_PORT=8080 +POSTGRES_USER=messenger +POSTGRES_DB=messenger +POSTGRES_PASSWORD= +POSTGRES_HOST_PORT=5433 +VALKEY_PASSWORD= +VALKEY_HOST_PORT=6380 +LOG_LEVEL=INFO +SHUTDOWN_TIMEOUT=5 +# S3 (SeaweedFS): the root pair and the signing key stay with the s3 server; +# api, worker and cleaner have their own users created by s3-bootstrap. +S3_HOST_PORT=8334 +S3_ROOT_ACCESS_KEY= +S3_ROOT_SECRET_KEY= +S3_JWT_SIGNING_KEY= +S3_API_ACCESS_KEY= +S3_API_SECRET_KEY= +S3_WORKER_ACCESS_KEY= +S3_WORKER_SECRET_KEY= +S3_CLEANER_ACCESS_KEY= +S3_CLEANER_SECRET_KEY= +# RabbitMQ (lab 5): only relay and worker get the password. +BROKER_PASSWORD= +BROKER_HOST_PORT=5673 +WORKER_PREFETCH=2 +RENDER_MEMORY_MB=768 +UPLOAD_MAX_UNFINISHED=300 +# Observability (lab 6): Grafana on 127.0.0.1, admin password generated by +# make env. Telemetry knobs (defaults = full telemetry; track 1 changes them): +# OTEL_SDK_DISABLED=true switches the SDK off in api, worker and relay; +# OTEL_TRACES_SAMPLER_ARG is the share of root traces kept (0..1); +# OTEL_METRIC_EXPORT_INTERVAL is in ms; TELEMETRY_HISTOGRAM_BUCKETS is +# default or coarse. +GRAFANA_HOST_PORT=3180 +GRAFANA_ADMIN_PASSWORD= +OTEL_SDK_DISABLED=false +OTEL_TRACES_SAMPLER_ARG=1.0 +OTEL_METRIC_EXPORT_INTERVAL=15000 +TELEMETRY_HISTOGRAM_BUCKETS=default diff --git a/.gitignore b/.gitignore index b5a7189..634c6b4 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ data/ backups/ # Runtime/build artifacts .venv/ +.local-tools/ __pycache__/ *.py[cod] node_modules/ @@ -25,8 +26,18 @@ bin/ obj/ coverage/ *.log +!evidence/**/raw/*.log .DS_Store .idea/ .vscode/ +# Temporary benchmark state and self-check results are not submission evidence. +bench/.bench.lock +evidence/failover/quick-*/ +evidence/rollout/quick-*/ +evidence/scaling/quick-*/ +evidence/uploads/quick-*/ +evidence/reconcile/quick-*/ +evidence/queue/quick-*/ +evidence/telemetry-cost/quick-*/ # Keep small, sanitized evidence summaries in evidence/ under version control. # Inspect git diff --cached: ignore rules are not a secret scanner. diff --git a/.python-version b/.python-version new file mode 100644 index 0000000..24ee5b1 --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.13 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c989a56 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,306 @@ +# AGENTS.md — мессенджер MTUSI, лабораторная 6 + +REST API мессенджера с вложениями-изображениями и фоновой обработкой: +реплики API за HAProxy; PostgreSQL — источник истины (данные, сессии, +ключи идемпотентности, метаданные вложений, **задания обработки**); +Valkey — кэш карточек чатов; S3 (SeaweedFS) — staging и опубликованные +файлы; RabbitMQ — сообщения о заданиях; relay — outbox → брокер; worker — +обработка изображений в отдельном процессе; cleaner — уборка и сверка. +Загрузка отвечает **202 `queued`**, готовность клиент узнаёт из метаданных +(`ready` с вариантами `thumbnail`, `crop`, `optimized` или `failed` с +`error_code`). Бизнес-код перенесён из лабы 5 (`mtusi2026lab5-vladimirceva`) без +изменения поведения; в лабе 6 добавлена наблюдаемость: OpenTelemetry SDK в api, +relay и worker, Collector, Prometheus, Loki, Tempo, Grafana, перенос trace +context через очередь, SLO и alerts. Цель — **«5»**: уровни 3 и 4 `README.md` +и трек 1 «Цена наблюдаемости». + +**Состояние (16 ноября 2026).** Лаба 6 и трек 1 завершены локально. +Код приложения заморожен: `src_sha256` 81c47ffc…; Git подключён к Gitea, +база `main@470d9d6`. На машине замеров прошли 38 unit, 178 isolated +(все resilience hooks 0), 34 fault и 22/22 telemetry-check. Полная метка +`evidence/telemetry-cost/baseline-after-restart/`: 15/15 за 48,9 мин, +без flags, потерь и host_warnings, прирост swap 0; T1 и T3 опровергнуты, +T2 и T4–T7 подтверждены, S1–S5 выполнены. Таблицы и выводы — `REPORT.md`. +Финальные lint/check и повторный isolated (178 passed, все resilience 0) +прошли; доказательство `evidence/tests/final-check-20261116.txt`, всё своё остановлено. +Первая `baseline` прервана при host swap и сохранена; перед выбранной +меткой Docker перезапущен. Пользователь согласовал PostgreSQL профиля +2 → 1 CPU (сумма 9,75 CPU) под Apple M4 с 10 ядрами и автономное +прохождение всех шагов. ВМ — 10 CPU / 7,65 ГиБ; точный минимум памяти +6,125 + 1,5 = 7,625 ГиБ. Запуск на старом Docker Desktop — через +`tools/docker-compat/` (Compose 5.6.1, см. отчёт). Гипотезы и пороги +записаны до замеров и не переписывались. Рабочая конфигурация — full. + +Стек: Python 3.13, FastAPI, uvicorn, pydantic v2, SQLAlchemy Core 2.1 + +asyncpg, alembic, argon2-cffi, redis-py, aiobotocore 3.x, aio-pika 10, +Pillow 12 (только в процессе рендера), OpenTelemetry API/SDK/OTLP-HTTP 1.45; +PostgreSQL 18.6, Valkey 9.1.2, HAProxy 3.4.6, SeaweedFS 4.48, RabbitMQ 4.3.7, +OpenTelemetry Collector contrib 0.164, Prometheus 3.15, Loki 3.7, Tempo 3.1, +Grafana 13.3; uv, pip + `requirements.txt` с хешами (в образе), pytest + httpx. + +## 1. Где инструкции и как их читать + +Codex сам загружает `AGENTS.md` от корня до рабочего каталога (вместе — не +больше 32 КиБ). Правила слоёв лежат глубже, поэтому **перед правкой файла +прочитай каждый `AGENTS.md` на пути к нему** (`cat`). + +| Файл | Когда читать | +|---|---| +| `AGENTS.md` (этот) | всегда: запреты, команды, карта, Definition of Done | +| `src/AGENTS.md` | любая правка в `src/`: слои, импорты, процессы, ошибки, конфиг (таблица переменных), логи, `src/telemetry/` | +| `src/api/AGENTS.md` | роуты, схемы, middleware, вход, `X-Instance-Id`, `Idempotency-Key`, вложения | +| `src/services/AGENTS.md` | бизнес-правила, загрузка, worker, relay, replay, уборка и сверка | +| `src/storage/AGENTS.md` | PostgreSQL: транзакции, гонки, вложения, задания и fencing; кэш; объекты S3 | +| `migrations/AGENTS.md` | схема, новые ревизии, совместимость с работающей версией | +| `infra/AGENTS.md` | `Dockerfile`, `compose.yaml`, S3, брокер, relay, worker, HAProxy, `scripts/*`, `infra/otel/` (Collector, хранилища телеметрии, Grafana, правила, runbooks) | +| `student-tests/AGENTS.md` | свои тесты, отдельные стенды, проверки отказов | +| `evidence/AGENTS.md` | доказательства для `REPORT.md` | +| `bench/AGENTS.md`, `bench/RUNBOOK.md` | нагрузочный стенд; замеры трека 1 по шагам | + +Ещё Codex читает **правила команд** `.codex/rules/messenger.rules` (только у +доверенного проекта; после правки — перезапуск Codex; проверка — `codex +execpolicy check --pretty --rules "$PWD/.codex/rules/messenger.rules" make +wipe`) и **навыки** `.agents/skills/`: `lab6-bench` (замеры трека 1 по RUNBOOK), +`messenger-stand` (стенд, проверки телеметрии и alerts, демонстрация). Они дублируют раздел 2, +но не заменяют его. + +Конфликт: глубже — уточняет, но не отменяет раздел 2. Прямая просьба +пользователя важнее этих файлов, кроме пунктов «спросить». + +## 2. Нельзя + +1. **Менять skeleton преподавателя** (спросить): `contracts/`, `tests/`, + `scripts/` (кроме своих `restart.sh`, `stop-one.sh`, + `rolling-update.sh`, `lab6.py`), `lab.json`, `README.md`, `COURSE.md`, + `CONTRIBUTING.md`, `MAINTAINERS.md`, `Dockerfile.example`, + `compose.example.yaml`, `infra/README.md`, `requirements-dev.txt`, + `evidence/README.md`, `examples/`, `.github/`, верх `Makefile` до строки + `=====`. Публичный тест упал — чиним приложение. +2. **Подгонять тесты под код**: ослаблять `assert`, менять ожидаемый + статус, `skip`/`xfail`, удалять тест. +3. **Состояние в памяти процесса, от которого зависит корректность**: + данные, сессии, ключи, метаданные и **задания** — только PostgreSQL; + байты — только S3; сообщение брокера — только подсказка «посмотри + задание». `--workers`, gunicorn, `reload`; sticky session. Уборка и + сверка — только `cleaner`, публикация — только `relay`, обработка — + только `worker`. +4. **Порты реплик наружу и `container_name` у `api`**; консоль, master, + volume, filer SeaweedFS, мониторинг LB, management RabbitMQ — наружу. +5. **Файлы конфигурации приложения**: настройки — только переменные + окружения (`src/config.py`). +6. **JSON-логи, structlog, `print`** вместо логгера (`src/log.py`). +7. **Писать в лог и телеметрию** (атрибуты span, метки метрик, записи Loki) текст сообщений, `display_name`, `title`, username, + `filename` (только длину), пароль, токен, ключи, их хэши, + `Authorization`, `Idempotency-Key`, тела, параметры SQL, оператора и + причину replay (только длины). Можно id, ключ объекта, размеры. +8. **Git без просьбы**: `commit`, `push`, `checkout`, `reset`, `stash`, + `rebase`, `clean`. Смотреть можно. +9. **Удалять данные стенда без просьбы** (спросить): `make wipe`, `docker + compose down -v`, `docker volume rm`, очистку очереди брокера, + `FLUSHALL`, `TRUNCATE`/`DROP`, удаление объектов мимо API, каталоги + меток в `evidence/`; `make replay APPLY=1`, `make reconcile APPLY=1` на + рабочем стенде. +10. **Секреты и `.env`** в git, образ, `evidence/`, вывод и отчёт; `COPY . + .`. Административную пару S3 — никому, кроме `s3`; пароль брокера — + только `rabbitmq`, `relay`, `worker`. +11. **Незакреплённые версии**: `latest`, тег без digest, пакет без lock. +12. **Новая зависимость** (спросить). +13. **Миграция, которая ломает работающую версию**: только expand; + применённую ревизию не править. +14. **`HTTPException`** в сервисах и хранилище, **403**, **422** наружу; + прозрачные повторы `POST`. +15. **Обходить sandbox Codex** (раздел 10). +16. **Выдумывать результаты**: в отчёт и `evidence/` — только реальный + вывод команд, которые ты запустил. Гипотезы T1–T7 и критерии S1–S5 не переписывать. + Число из чужой лабы в отчёт не брать. +17. **Чинить попутно найденное** без просьбы: записать в `KNOWN_ISSUES.md`. +18. **Менять код приложения ради замеров** (спросить). + +## 3. Порядок работы + +1. Откуда требование: `README.md` (рубрика), `contracts/observability.md` + (сигналы), `contracts/infrastructure.json`, `infra/otel/README.md` (задание), + `contracts/README.md`, `contracts/attachment-states.md`, + `contracts/jobs.schema.json`, `contracts/openapi.json`, `COURSE.md`. + Неясно — спроси. Ответ преподавателя — в раздел 12. +2. Прочитай нужные `AGENTS.md` и затрагиваемые файлы целиком. +3. Задача больше пары файлов — короткий план в чате. +4. Минимальный дифф. 5. Проверки раздела 8. 6. Отчёт — раздел 11. + +## 4. Команды + +| Команда | Что делает | +|---|---| +| `make install` / `make env [HOST_PORT=…]` | `uv sync` / `.env` со случайными паролями и ключами (существующий дополняется) | +| `make up` | postgres, valkey, s3, rabbitmq → migrate, s3-bootstrap → api × `API_REPLICAS` (2), relay, worker, cleaner → haproxy; Collector, Prometheus, Loki, Tempo, Grafana; ждёт healthy (у телеметрии — `running`) | +| `make stop` / `make down` / `make logs` / `make logs-pipeline` | остановить / удалить контейнеры (volume остаются) / журнал реплик / relay и worker | +| `make wipe` | удалить контейнеры и volume `pgdata`, `s3data`, `rmqdata`: только после `yes` | +| `make test [BASE_URL=...]` | публичный smoke (202, ready, оригинал, thumbnail 256×160) | +| `make defense` | шаги 2–3 защиты: worker стоп → 202 → ссылка → 409 → `restart.sh` → worker → ready | +| `make stop-worker` / `make start-worker` / `make pipeline-state` | worker; задания по состояниям и очередь брокера | +| `make replay [ERROR_CODE=…] [ATTACHMENT=…] [APPLY=1 OPERATOR=… REASON=…]` | реестр failed; с `APPLY=1` — возврат с аудитом (коды 0/3/1/2) | +| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | данные, токен, оригинал после рестарта LB, реплик, хранилищ и брокера | +| `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` / `make failover-each` | отказ одной реплики | +| `make student-test [BASE_URL=…] [EXPECT_REPLICAS=…]` | свои тесты против стенда (без отказов) | +| `make test-isolated` / `make failure-checks [FAULT_ARGS=-rP]` | отдельный стенд: всё выше / проверки отказов (в том числе pipeline) | +| `make attachment-failover` / `make s3-check` | вложение после остановки принявшей реплики / приватность bucket | +| `make replicas` / `instances` / `lb-stats` / `rolling-update` | реплики за LB | +| `make cleanup-once` / `make reconcile [APPLY=1] …` | уборщик (и staging) / сверка (dry-run по умолчанию) | +| `make db-up` / `run` / `run-relay` / `run-worker` / `migrate-local` | процессы на хосте рядом с хранилищами | +| `make lint` / `fmt` / `check` / `validate` · `requirements[-check]` | ruff; офлайн-проверки skeleton; `requirements.txt` из `uv.lock` | +| `make telemetry-check` | запрос и загрузка → трасса в Tempo ↔ запись в Loki, метрики без id, нет секретов (22 проверки) | +| `make trace-chain` | S3 остановлен → повтор: одна трасса API → relay → worker, retry и ready | +| `make alerts-test` / `make alerts-check` | promtool check и test правил / worker стоп и блокировка таблицы → firing → resolved (~6,5 мин) | +| `make telemetry-outage [OUTAGE_SECONDS=120]` | Tempo остановлен под нагрузкой: API и загрузки живы, потери считает Collector | +| `make grafana` / `make logs-telemetry` | адрес dashboard / журнал сервисов телеметрии | +| `make bench-telemetry [TELEMETRY_LABEL=…]` / `make bench-telemetry-quick` | трек 1 «Цена наблюдаемости» (`bench/RUNBOOK.md`); `quick-*` в отчёт не идут | +| `make bench-queue [QUEUE_LABEL=…]`, `bench-uploads`, `bench-reconcile`, `bench-failover`, `bench-rollout`, `bench-scaling` | профили лаб 3–5 (сохранены, в лабе 6 не обязательны) | + +Проверки ходят на `http://localhost:8180` (HAProxy). Внешние порты в +`.env`: `HOST_PORT` (8180), `POSTGRES_HOST_PORT` (5533), `VALKEY_HOST_PORT` (6480), +`S3_HOST_PORT` (8434), `BROKER_HOST_PORT` (5773), `GRAFANA_HOST_PORT` (3180); +порты Collector, Prometheus, Loki, Tempo наружу не публикуются; разовая +подмена — `make test BASE_URL=http://localhost:8190`. Тесты против рабочего стенда +оставляют данные; чистый прогон — `make test-isolated`. + +## 5. Карта кода + +``` +src/ python -m src (__main__ → early_stop.install() → main.run()): API + main.py create_app(): Db, кэш, хранилище, S3, места загрузок, пароли, роутеры + config.py Settings.from_env(): Database, Cache, ObjectStorage, Uploads, Cleaner, Broker, Pipeline, Relay, Telemetry + telemetry/ OpenTelemetry: sdk.py (провайдеры, экспорт, наблюдаемые инструменты), __init__.py (интерфейс для слоёв) + constants.py, log.py, errors.py, clock.py, domain.py, pagination.py, healthcheck.py, early_stop.py + images.py структурная проверка PNG/JPEG на входе API (stdlib) + db.py, cache.py, s3.py, uploads.py, passwords.py инфраструктура процесса + broker.py RabbitMQ (aio-pika): JobPublisher (confirms) и JobConsumer (qos, ack), формат сообщения + renderer.py ImageRenderer: процесс обработки на задание, лимиты, коды выхода → исходы + worker/ python -m src.worker: потребитель + WORKER_CONCURRENCY задач; render.py — дочерний процесс Pillow + relay/ python -m src.relay: outbox → брокер, аренды, потерянные; `replay` — реестр failed + cleaner/ python -m src.cleaner: брошенные загрузки, staging, сверка + api/ routes/, schemas, deps, identity, request_id, handlers + services/ User/Session/Chat/Message/Attachment, Processing, Relay, Replay, Cleanup, Reconcile + storage/ base.py (Storage, MaintenanceStorage, PipelineStorage), postgres.py, pipeline.py, cached.py, tables.py, objects.py +migrations/ 0001 лаба 2, 0002 ключи, 0003 вложения, 0004 задания, варианты, журнал replay, 0005 traceparent/tracestate заданий (expand) +student-tests/ тесты по HTTP; test_processing.py, test_pipeline.py; unit/test_telemetry.py, unit/test_trace_chain.py (без стенда, лаба 6); stand.py, fault_hook.py +bench/ нагрузочный стенд; профиль telemetry — трек 1 лабы 6 (bench/AGENTS.md), queue — лабы 5 +infra/ haproxy/, valkey/, s3/bootstrap.sh, rabbitmq/rabbitmq.conf, otel/ (collector.yaml, prometheus/, loki/, tempo/, grafana/, runbooks/) +scripts/ restart.sh, stop-one.sh, rolling-update.sh, lab6.py (свои); остальное — skeleton +.codex/rules/, .agents/skills/, evidence/, Dockerfile, compose.yaml, pyproject.toml, uv.lock, requirements.txt +``` + +Поток: HAProxy → реплика (401, 400, 404, 415, 413, 429 предела, 429 места, +тело, структура) → строка `pending` → PUT в staging → `queued` + задание +(одна транзакция) → **202**. Дальше без клиента: relay публикует задание с +подтверждением → worker захватывает с арендой → GET staging, рендер в +отдельном процессе, PUT оригинала и вариантов → фиксация `ready` +(fencing по номеру попытки) → ack. Подробно — `src/services/AGENTS.md`. + +## 6. Контракт: самое важное + +- Каждый ответ — `X-Request-Id` и `X-Instance-Id`; ошибка — `{"error": + {"code", "message", "request_id"}}`; 422 и 403 — никогда. +- Загрузка — PNG/JPEG ≤ 10 MiB, ≤ 40 млн пикселей; **202** `queued` только + после staging и задания в PostgreSQL; задание ждёт и без брокера и worker. +- Состояния `queued`/`processing`/`ready`/`failed`, варианты thumbnail, crop, + optimized, `error_code` у `failed`; байты не готового или `failed` — 409, + нет варианта — 404. Сообщение: до 10 видимых вложений чата, `failed` — 409. + Подробно — `contracts/`. + +## 7. Конфигурация, логи, Docker, зависимости + +**Переменные** читает только `src/config.py`; неверное значение — код 2. +Группы: `APP_*`, `LOG_LEVEL`, `DB_*`, `CACHE_*`, `S3_*`, `UPLOAD_*` +(`UPLOAD_MAX_UNFINISHED` — предел незавершённых заданий), `CLEANER_*`, +`STAGING_RETENTION_SECONDS`, `RECONCILE_*`, `BROKER_*`, `WORKER_*`, +`JOB_*`, `RENDER_MEMORY_MB`, `RELAY_*`, `OTEL_*`, `TELEMETRY_HISTOGRAM_BUCKETS`. +Таблица — `src/AGENTS.md`. +`WORKER_FAULT`, `RELAY_FAULT` — точки сбоя только для проверок отказов. + +**Логи**: строка на событие `время уровень логгер [rid=...] сообщение +key=value`. Строки `attachment processed …`, `job delivery skipped …`, +`reconcile pass finished …` разбирают `bench/` и тесты — имена полей не +менять. С лабы 6 запись журнала несёт `trace_id`/`span_id` и дублируется в +Loki по OTLP; имена метрик и меток — контракт `contracts/observability.md`, +dashboard и правила на них опираются (меняются вместе). + +**Docker, compose, S3, брокер, HAProxy** — `infra/AGENTS.md`. Числа менять +только вместе: аренда задания `JOB_TIMEOUT_SECONDS + JOB_LEASE_MARGIN_SECONDS` +(60 + 20 с) > времени рендера и записи; `timeout server` пути загрузки 40 с +> 5 + 30 с; `CLEANER_GRACE` 900 с > 21 с; дренаж замены 90 с > 40 с. + +**Зависимости**: `pyproject.toml` → `uv lock` → `make requirements` → `make +requirements-check` → пересборка образа. + +## 8. Definition of Done + +- [ ] `make fmt`, затем `make lint` — без ошибок; +- [ ] `make test-isolated` — в `results` все 0; +- [ ] правка хранилища, вложений, pipeline, уборщика, сверки, сессий, + ключей, кэша, клиентов, таймаутов — ещё `make failure-checks`; +- [ ] правка `compose.yaml`, `haproxy.cfg`, `infra/`, `scripts/*` — `make + up`, `test`, `defense`, `s3-check`, `attachment-failover`, `make + test-persistence ACTION_SCRIPT=scripts/restart.sh`, `failover-each`; +- [ ] правка схемы — новая expand-ревизия, `alembic check` чистый; +- [ ] правка `Dockerfile`, зависимостей — `make up`, `test`, + `requirements-check`; +- [ ] правка телеметрии, `infra/otel/`, dashboard, правил — `make telemetry-check`, + `make alerts-test`; перенос контекста — ещё `make trace-chain`; +- [ ] правка `bench/` — самопроверки разбора и `make bench-telemetry-quick`; +- [ ] новое поведение из рубрики — тест в `student-tests/`; +- [ ] изменилось описанное в `REPORT.md`, `evidence/`, `AGENTS.md` — + обновлено там же; +- [ ] остановлены серверы и контейнеры, которые ты запустил. + +Не смог выполнить пункт — так и напиши, с причиной. + +## 9. Если тест или проверка упали + +Воспроизведи, прочитай вывод целиком, определи причину: дефект приложения +→ код; ошибка теста (противоречит контракту, случайная) → тест, с +объяснением; стенд (чужой порт, старый образ, не тот `BASE_URL`, остатки +прогона, сервис не healthy) → стенд. Неясно — спроси. `tests/` не +правится никогда; на загруженном хосте проверки отказов могут ложно +падать — один перезапуск и сказать. + +## 10. Особенности Codex + +- В sandbox нет сети и часто нет docker: запроси запуск вне sandbox + (правила `.codex/rules/`) или попроси пользователя; команду — дословно. +- Долгие команды (`make bench-telemetry`, `make failure-checks` — ~8 мин, + `make alerts-check` — ~6,5 мин) — в фоне: `nohup make … > /tmp/x.log 2>&1 &`, затем `tail`. +- Порт контейнера на macOS держит `com.docker.backend`: процесс по порту не + убивать, чужие контейнеры не трогать — выбрать другие порты (`make env + HOST_PORT=… … GRAFANA_HOST_PORT=…` до первого `make up`). +- Этот файл ≤ ~26 КБ (`wc -c`); правило слоя — во вложенный `AGENTS.md`. + +## 11. Отчёт пользователю + +По-русски, коротко: что сделано; какие проверки и с каким итогом +(`N passed`, `PASS: lab6 ...`, `results: {...}`, метки `evidence/…`); что +не проверено и почему; что записано в `KNOWN_ISSUES.md`. + +## 12. Согласования с преподавателем + +Договорённости, которых нет в skeleton. Каждую упомянуть в `REPORT.md`. + +| Дата | Договорённость | Где учтено | +|---|---|---| +| 2026-10-20 | Лаба 4: «пустой текст» сообщения — и `""`, и строка из одних пробелов. `" "` с ≥ 1 вложением — 201, без вложений — 400 | `src/api/schemas.py` (`CreateMessage`), `student-tests/test_attachments.py`, `REPORT.md` | + +## 13. Стиль кода + +- ruff: строка 88, py313; формат — `make fmt`. Аннотации везде. Скрипты на + `python3` хоста (`student-tests/stand.py`, `fault_hook.py`, + `scripts/lab6.py`, `bench/`) — stdlib, Python 3.9+. +- Методы сервисов и изменяющие методы хранилища — keyword-only. +- Комментарий объясняет причину, а не пересказывает код; пишем кратко, + по-русски. Логи и + `error.message` — по-английски. +- Коммиты (только по просьбе): английский, conventional. + +## 14. Документы решения + +`REPORT.md` (отчёт, гипотезы T1–T7, ответы защиты), `evidence/`, +`KNOWN_ISSUES.md`, `bench/RUNBOOK.md`. Доказательства лаб 3–5 — в их +репозиториях; compose-проект — `vladimirceva-lab6`. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..5947bc0 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,65 @@ +# Один образ на все процессы лабы 6: API (`python -m src`), миграции, +# relay (`-m src.relay`), worker (`-m src.worker`, Pillow — только в его +# дочернем `-m src.worker.render`) и уборщик (`-m src.cleaner`). Процесс +# выбирает entrypoint сервиса compose. Правила — infra/AGENTS.md. +# +# Базовый образ один на оба stage и закреплён точной патч-версией плюс +# digest мультиарх-индекса (amd64 и arm64): venv из deps работает только с +# тем же интерпретатором. Чтобы обновить, взять новый тег и значение поля +# Digest, которое печатает buildx imagetools inspect для этого тега. + +# deps: зависимости строго по requirements.txt (экспорт uv.lock с хешами). +# У asyncpg, greenlet и argon2-cffi-bindings есть готовые колёса для +# linux amd64/arm64: компилятор в образе не нужен +FROM python:3.13.15-slim-trixie@sha256:7c61056e61ac89e852de05f3dc6fa51a6dd2181797bceed46aa725dd7cb2cd3b AS deps + +ENV PIP_NO_CACHE_DIR=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 + +RUN python -m venv /opt/venv +COPY requirements.txt /tmp/requirements.txt +# --require-hashes: пакет с другим хешем или без пина — сборка падает; +# --no-deps: ставится ровно список из файла, без догрузки зависимостей; +# --only-binary: сборка из исходников (sdist) запрещена +RUN /opt/venv/bin/pip install --require-hashes --no-deps --only-binary=:all: \ + -r /tmp/requirements.txt + + +# runtime: интерпретатор базового образа, venv и код; без pip-кэша и тестов +FROM python:3.13.15-slim-trixie@sha256:7c61056e61ac89e852de05f3dc6fa51a6dd2181797bceed46aa725dd7cb2cd3b AS runtime + +RUN groupadd --system --gid 10001 messenger \ + && useradd --system --uid 10001 --gid messenger --no-create-home \ + --home-dir /nonexistent --shell /usr/sbin/nologin messenger + +# Фиксированный порог mmap в 128 KiB: всё крупнее glibc выделяет через +# mmap, и BytesIO с телом загрузки (до 10 MiB) расширяется mremap без +# копирования. По умолчанию порог плавающий — после первой загрузки glibc +# задирает его почти до 10 MiB, буфер переезжает в кучу, и при realloc в +# памяти на мгновение оказываются две копии тела +ENV PATH=/opt/venv/bin:$PATH \ + PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + MALLOC_MMAP_THRESHOLD_=131072 \ + APP_HOST=0.0.0.0 \ + APP_PORT=8080 + +WORKDIR /app + +# владелец файлов — root, процесс от messenger может их только читать. +# Миграции едут в том же образе: сервис migrate запускает его с командой +# `python -m alembic upgrade head` +COPY --from=deps /opt/venv /opt/venv +COPY src ./src +COPY alembic.ini ./ +COPY migrations ./migrations + +USER messenger:messenger + +EXPOSE 8080 + +HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --start-interval=1s \ + --retries=3 CMD ["python", "-m", "src.healthcheck"] + +# без shell-обёртки: python становится PID 1, и SIGTERM приходит прямо ему +CMD ["python", "-m", "src"] diff --git a/KNOWN_ISSUES.md b/KNOWN_ISSUES.md new file mode 100644 index 0000000..9e8efa3 --- /dev/null +++ b/KNOWN_ISSUES.md @@ -0,0 +1,153 @@ +# Известные проблемы + +Замечены по ходу работы; без отдельной просьбы код не трогаем (корневой +`AGENTS.md`, раздел 2, п. 17). Формат: что, где, симптом, предложение. Исправленное +удаляется отсюда. + +## Лаба 6 + +### SLI ready/30 с условен по успешным вложениям + +`messenger:attachment_ready_30s:ratio_7d` делит корзину ≤ 30 с на count +гистограммы `messenger_attachment_time_to_ready_seconds`. Наблюдение пишется +только после `ready`, поэтому failed и ещё ожидающие задания не входят в +знаменатель. Это SLI задержки уже успешных вложений, а не доля всех принятых +202, завершившихся за 30 с. Отчёт уточнён по фактической формуле; правила и +измеренный код сохранены. Для полного SLO успеха нужен отдельный учёт +принятых, failed и просроченных незавершённых заданий. API SLO при этом +определён отдельно по ответам API без 5xx. + +### Docker Desktop 28: запуск через локальный Compose + +На машине замеров Docker CLI 28.0.4 подменяет `OTEL_RESOURCE_ATTRIBUTES` +служебным `docker.cli.cobra.command_path` (docker/cli#4958), из-за чего +приложение корректно отказывается запускаться. Прямой Compose 2.34.0 +устраняет подмену, но его `up --wait` завершается ошибкой на сервисе +cleaner с отключённым healthcheck. Обход без изменения приложения: +`sh tools/docker-compat/setup.sh`, затем +`export PATH="$PWD/tools/docker-compat:$PATH"` — официальный Compose +5.6.1 с закреплённой SHA-256, остальные команды идут в прежний Docker CLI. +Системная установка не меняется. Проверка конфигурации, старт и smoke +с этой обёрткой прошли; команды без неё на старом Docker затронуты. + +### Потери SDK при недоступном Collector не считаются метрикой + +Очередь `BatchSpanProcessor`/`BatchLogRecordProcessor` (2048 элементов) +при переполнении молча отбрасывает новое, а неудачная отправка видна +только строкой stdout `Failed to export …` (с лабы 6, уровень 4, — не +чаще раза в минуту на логгер, со счётчиком пропущенных `suppressed=N`; поэтому +в `bench/` их число — нижняя оценка). +Счётчика отброшенного в SDK 1.x нет; потери считаются на стороне +Collector (`otelcol_receiver_refused_*`, `otelcol_exporter_send_failed_*`), +а это не покрывает случай «упал сам Collector». Предложение: свой +`SpanProcessor`-обёртка со счётчиком отброшенного, если понадобится. + +### Снимок очереди пропадает вместе с relay + +Глубину очереди и возраст старейшего задания (`messenger_job_queue_*`) +снимает relay. Relay остановлен — ряды уходят из экспортёра Collector через +`metric_expiration` 3 мин, и `MessengerQueueLagGrowing` перестаёт +срабатывать, хотя задания стоят. Сам застой виден по росту `outbox` до +остановки и по `messenger_relay_jobs_total`. Предложение: alert на +`absent(messenger_job_queue_oldest_age_seconds)` 5 мин. + +### Ожидающие пула считаются только внутри `Db` + +`db_client_connection_pending_requests` — счётчик в `src/db.py` от входа в +`transaction()`/`read()` до выдачи соединения (включает BEGIN и pre-ping). +Проба готовности (`ping`) мимо него. Для «ждёт соединения» этого +достаточно, для точного времени ожидания — нет (нужен histogram). + +### У Collector, Loki и Tempo нет healthcheck + +В образах нет оболочки и HTTP-клиента, поэтому `make up --wait` ждёт +только `running`. Живость видна в Prometheus (`up{job=…}`) и на панели +«Scrape targets up». Сразу после старта Loki пишет `error getting ingester +clients … empty ring` (кольцо ещё не собралось), Tempo — `error calling +scheduler … no jobs found` (нечего уплотнять): это не отказы. + +## Перенесено из лабы 5 + +Поведение лабы 5 в лабе 6 не менялось, записи актуальны. + +### Смесь версий при замене реплик лабы 4 на лабу 5 + +`scripts/rolling-update.sh` меняет реплики по одной. Пока работает хоть +одна реплика лабы 4, её загрузки отвечают 201 `ready`, задания не пишутся, +вариантов у таких вложений нет (метаданные `ready` с `variants: []`, +`?variant=thumbnail` — 404). Схема 0004 это допускает (expand), но +клиент на время замены видит два поведения. Предложение: первый релиз +лабы 5 выкатывать `make down` + `make up` (с простоем) или дописать +разовую команду, которая ставит задания готовым вложениям без вариантов. + +### JPEG без таблиц квантования проходит проверку API + +`src/images.py:_inspect_jpeg` проверяет маркеры, кадр и скан, но не +наличие DQT. Такой файл получает 202, а worker переводит его в `failed` +с `invalid_image` (`student-tests/test_processing.py:: +test_undecodable_image_fails_with_safe_code`). Контракт требует 415 для +заведомо повреждённых файлов на входе. Предложение: в `_inspect_jpeg` +собирать номера таблиц DQT и требовать, чтобы каждая компонента кадра +ссылалась на определённую до SOS. + +### Эвристика потерянных сообщений видит только «ready» в очереди + +`src/services/relay.py`: `republish_lost` срабатывает, когда в очереди нет +сообщений, готовых к выдаче (`message_count` пассивного объявления), а +задание опубликовано дольше `RELAY_REPUBLISH_AFTER`. Сообщения, уже +выданные worker и ждущие во внутренней очереди процесса (prefetch больше +concurrency), в этот счёт не входят. При очень большом prefetch и долгих +заданиях relay опубликует их повторно: исход верный (старая попытка +станет `stale`), но работа брокера и worker лишняя. Предложение: брать +ещё `messages_unacknowledged` (management API) или не республиковать, +пока у очереди есть потребители с неподтверждёнными сообщениями. + +### Долгий отказ PostgreSQL и предел доставок quorum-очереди + +`src/worker/main.py:_one`: PostgreSQL не ответил на захвате — сообщение +возвращается в очередь через 1 с. У quorum-очереди RabbitMQ 4 есть +предел повторных доставок (по умолчанию 20), после него сообщение +отбрасывается. Задание при этом цело в PostgreSQL и вернётся через +`republish_lost`, но не раньше `RELAY_REPUBLISH_AFTER`. Предложение: +пауза перед возвратом с ростом или собственный `x-delivery-limit` под +ожидаемую длину отказа. + +### Шум aiormq в журнале при остановке брокера + +При `docker compose stop rabbitmq` библиотека aiormq пишет `ERROR` и +traceback `CONNECTION_FORCED` в журнал relay и worker, хотя дальше их +код штатно переподключается (строки `broker … failed`, затем `broker +consuming`). Предложение: поднять уровень логгера `aiormq.connection` до +`CRITICAL` в `src/log.py` и оставить только свои строки. + +### SAWarning в `alembic check` + +`alembic check` (alembic 1.20.0, SQLAlchemy 2.1.1) печатает `SAWarning: +Can't validate argument 'dialect_options'; can't locate any SQLAlchemy +dialect named 'dialect'` из `migrations/env.py:54`, затем «No new upgrade +operations detected» (в лабе 6 не переснято, миграция `0005` — две колонки +`NULL`, расхождений нет). Предупреждение +появляется при сравнении отражённых индексов, на результат проверки не +влияет; источник не выяснен. Предложение: проверить на минимальной схеме +с одним частичным индексом и, если это библиотека, закрепить фильтр +`warnings` только для этой строки в `env.py` или дождаться исправления. + +## Перенесено из лабы 3 (bench/, серии трека 1 лабы 3) + +Профили лабы 3 в лабе 6 сохранены, но не обязательны. + +### Возобновление прерванной серии требует доработки + +Статический анализ `bench/run.py:run_scaling` и `scaling_cell`: ветка +`resume` сохраняет прежний `meta.aborted`, а финальная проверка этого +поля возвращает ошибку даже после завершения оставшихся ячеек. Повтор +незавершённой ячейки добавляет строки с теми же номерами. Предложение: +восстанавливать только незавершённую ячейку и снимать `aborted` после +успешного продолжения. + +### Подпись насыщения для A/B с одной конфигурацией + +В `bench/plots.py:saturation` единственная точка возвращает `None`, а +`main` трактует это как продолжающийся рост ≥ 10 %. Предложение: +отдельно печатать «недостаточно конфигураций» при числе точек меньше +двух. diff --git a/MR_COMMANDS.md b/MR_COMMANDS.md new file mode 100644 index 0000000..52afe64 --- /dev/null +++ b/MR_COMMANDS.md @@ -0,0 +1,42 @@ +# Публикация решения лабораторной 6 + +Выполнить из терминала один раз. Локальная ветка сейчас `main`, ветка решения ещё не создана. +Имя и email автора Git уже настроены. + +```sh +cd "/Users/anastasia/Высоконагруженные/mtusi2026lab6-vladimirceva/mtusi2026lab6-vladimirceva" +git switch -c solution/bvt2301-vladimirceva +git add --all +git diff --cached --check +git diff --cached --stat +git commit -m "feat: implement lab 6 observability and telemetry cost research" +git push -u origin solution/bvt2301-vladimirceva +``` + +Если ветка уже была создана, вместо команды `git switch -c ...` использовать +`git switch solution/bvt2301-vladimirceva`. + +Скопировать подготовленное описание MR в буфер обмена macOS и открыть исходный репозиторий: + +```sh +pbcopy < MR_DESCRIPTION.md +open "https://gitea.privcloud.tech/mtusi2026/mtusi2026lab6" +``` + +В Gitea открыть создание Pull Request (MR) и выбрать: + +| Поле | Значение | +| --- | --- | +| Целевой репозиторий | `mtusi2026/mtusi2026lab6` | +| Базовая ветка | `main` | +| Репозиторий-источник | `Anastasia_Vladimirceva/mtusi2026lab6-vladimirceva` | +| Ветка-источник | `solution/bvt2301-vladimirceva` | +| Заголовок | `ЛР 6 — БВТ2301 — Владимирцева — на 5` | +| Описание | Содержимое `MR_DESCRIPTION.md` (уже скопировано командой pbcopy) | + +Проверить вкладку изменённых файлов и создать запрос преподавателю. +Сохранённые результаты измерений включаются в коммит; `.env`, `.venv`, `.local-tools` +и самопроверочные метки `quick-*` исключены правилами Git. + +Репозиторий-источник подтверждён как fork указанного репозитория преподавателя; +обе исходные ветки `main` на момент аудита указывают на skeleton `470d9d6`. diff --git a/MR_DESCRIPTION.md b/MR_DESCRIPTION.md new file mode 100644 index 0000000..fbebc91 --- /dev/null +++ b/MR_DESCRIPTION.md @@ -0,0 +1,68 @@ +# ЛР 6 — БВТ2301 — Владимирцева — на 5 + +Автор / группа: Анастасия Владимирцева, БВТ2301. +Целевая оценка: 5. Трек: 1 «Цена наблюдаемости». + +В мессенджер с API-репликами, PostgreSQL, S3 и фоновым конвейером добавлена +наблюдаемость: OpenTelemetry SDK → Collector → Prometheus/Loki/Tempo → Grafana. +По загрузке доступна сквозная трасса API → relay → worker с retry; остановка +backend телеметрии сохраняет работу API и обработку вложений. + +Из lab5 сохранены бизнес-API, durable jobs/outbox, идемпотентность, роли S3, +worker, relay, cleaner и проверки отказов. В lab6 добавлены SDK-инструментация, +миграция контекста W3C, provisioning dashboard и источников, SLI/SLO, alerts и runbooks. + +Запуск из чистого clone описан в [REPORT.md](REPORT.md#запуск-из-чистого-clone). +Для старого Docker Desktop на macOS предусмотрен локальный Compose 5.6.1 +с закреплённой SHA-256: `sh tools/docker-compat/setup.sh`, затем +`export PATH="$PWD/tools/docker-compat:$PATH"`. Основные команды: + +```sh +make install +make env +make up +make test +make telemetry-check +make alerts-test +python3 tools/audit_incidents.py +make trace-chain +make telemetry-outage +make stop +``` + +Исследование: пять вариантов off/full/head/tail/balanced × три повтора, +одинаковая открытая нагрузка, метка +[`baseline-after-restart`](evidence/telemetry-cost/baseline-after-restart/summary.md). +15/15 прогонов без flags, host_warnings и наблюдаемых потерь; исходный код +совпадает с хешем паспорта. T1 и T3 опровергнуты, T2 и T4–T7 подтверждены. +Все критерии S1–S5 balanced выполнены: сохранены 84/84 трасс 500, 99/99 +медленных записей и 42/42 цепочек failed; span Tempo — 5,1 % full, +ряды Prometheus — 10 % full. CPU balanced близок к full (+9 % к off); +head уменьшает надбавку CPU вдвое и теряет большую часть редких трасс. + +Проверки и доказательства: + +- [Подготовка и unit/selftest](evidence/tests/host-preflight-20261116.txt). +- [178 isolated, 34 fault, 22/22 telemetry](evidence/tests/host-stand-20261116.txt). +- [Финальные проверки после исследования](evidence/tests/final-check-20261116.txt). +- [Трасса с retry](evidence/telemetry/trace-chain.txt), + [alerts firing/resolved](evidence/alerts/alerts-check.txt), + [отказ Tempo](evidence/telemetry/outage.txt). +- [Полный отчёт и таблица критериев](REPORT.md). + +Ограничения: один хост, 140 с нагрузки за прогон, три повтора и одна интенсивность; +PostgreSQL профиля адаптирован до 1 CPU под машину с 10 ядрами до измерений. +SLI ready/30 с условен по успешным вложениям; failed и ожидающие задания +контролируются другими сигналами. Дополнительные ограничения SDK и сохранённого +бизнес-кода перечислены в [KNOWN_ISSUES.md](KNOWN_ISSUES.md). + +Источники: документация OpenTelemetry, W3C Trace Context, Prometheus, Loki, +Tempo, Grafana и материалы задания. ИИ использовался при разработке и подготовке +текста; числа и выводы подтверждены командами и сохранёнными результатами. + +- [x] Возможности текущей и предыдущей лабораторных проверены; ограничения объявлены. +- [x] Контракт, README задания и публичные tests не изменены и не ослаблены. +- [x] make check и make test выполнены; реальный вывод приложен. +- [x] Сценарии отказов и безопасности выбранного уровня воспроизведены. +- [x] Локальный .env и кэш инструментов исключены из Git; секреты в отчёт не вставлялись. +- [x] REPORT.md содержит инструкцию именно этого решения и результаты исследования. diff --git a/Makefile b/Makefile index 5d86d17..a85fffa 100644 --- a/Makefile +++ b/Makefile @@ -28,3 +28,490 @@ test-persistence: test-failover: @test -n "$(ACTION_SCRIPT)" || (echo "Set ACTION_SCRIPT to your implemented executable stop-one hook"; exit 2) $(PYTHON) tests/resilience.py --mode failover --action-script "$(ACTION_SCRIPT)" --base-url "$(BASE_URL)" $(TLS_ARGS) + + +# =========================================================================== +# Собственные цели решения. Цели skeleton выше (help, check, validate, test, +# load, test-persistence, test-failover) не менять: в следующей лабе +# Makefile придёт новый, свои цели переносятся в него слиянием. +# =========================================================================== + +# .env: подстановки compose и окружение приложения на хосте. Без него — +# значения по умолчанию ниже (пароли и ключи пустые: сначала `make env`) +-include .env + +IMAGE ?= mtusi-messenger-vladimirceva:lab6 +# порт HAProxy на 127.0.0.1 — единственный порт API стенда на хосте +HOST_PORT ?= 8080 +# цели skeleton (test, load, test-persistence, ...) по умолчанию ходят на +# 8080; если BASE_URL не задан в команде или окружении — на LB своего +# стенда (HOST_PORT из .env), чтобы не попасть в чужой стенд на 8080 +ifeq ($(origin BASE_URL),file) +BASE_URL = http://localhost:$(HOST_PORT) +endif +# лаба 6: Grafana стенда на 127.0.0.1 +GRAFANA_HOST_PORT ?= 3180 +# порт сервиса на хосте (make run): другой, чем у стенда, — оба могут +# работать одновременно +RUN_PORT ?= 8081 +POSTGRES_USER ?= messenger +POSTGRES_DB ?= messenger +POSTGRES_HOST_PORT ?= 5433 +VALKEY_HOST_PORT ?= 6380 +S3_HOST_PORT ?= 8334 +BROKER_HOST_PORT ?= 5673 +SESSION_TTL_SECONDS ?= 3600 +# реплик API за HAProxy; разово — `make replicas API_REPLICAS=3` +API_REPLICAS ?= 2 +DC = docker compose +UV_EXPORT = uv export --frozen --no-dev --no-emit-project --no-header --format requirements.txt +# долгие замеры на macOS — под caffeinate: ноутбук не уснёт по простою +CAFFEINATE := $(shell command -v caffeinate >/dev/null 2>&1 && echo caffeinate -isu) + +# --- приложение на хосте ---------------------------------------------------- + +.PHONY: install +install: + uv sync + +# окружение сервиса и миграций на хосте: хранилища стенда на 127.0.0.1, +# пароли и ключи пользователя API в S3 из .env. .env читается в рецепте, а +# не при разборе Makefile: так первый запуск видит и файл, только что +# созданный `make env`. Рецепт без эха — секреты не печатаются +LOCAL_ENV = set -a; . ./.env; set +a; \ + export DB_HOST=127.0.0.1 DB_PORT="$$POSTGRES_HOST_PORT" DB_NAME="$$POSTGRES_DB" \ + DB_USER="$$POSTGRES_USER" DB_PASSWORD="$$POSTGRES_PASSWORD" CACHE_HOST=127.0.0.1 \ + CACHE_PORT="$$VALKEY_HOST_PORT" CACHE_PASSWORD="$$VALKEY_PASSWORD" \ + S3_ENDPOINT="http://127.0.0.1:$$S3_HOST_PORT" S3_ACCESS_KEY_ID="$$S3_API_ACCESS_KEY" \ + S3_SECRET_ACCESS_KEY="$$S3_API_SECRET_KEY" BROKER_HOST=127.0.0.1 \ + BROKER_PORT="$$BROKER_HOST_PORT" BROKER_PASSWORD="$$BROKER_PASSWORD" \ + OTEL_SDK_DISABLED=true +# ↑ лаба 6: процессы на хосте без телеметрии — OTLP Collector наружу не +# опубликован +# worker на хосте — ключи своего пользователя S3, а не API +WORKER_ENV = $(LOCAL_ENV); export S3_ACCESS_KEY_ID="$$S3_WORKER_ACCESS_KEY" \ + S3_SECRET_ACCESS_KEY="$$S3_WORKER_SECRET_KEY" + +# PostgreSQL, Valkey и S3 из compose, миграции с хоста, затем один процесс +# сервиса на 127.0.0.1:RUN_PORT без LB, текстовые логи в stdout; стоп — +# Ctrl+C. Срок сессии — `make run SESSION_TTL_SECONDS=2` +.PHONY: run +run: migrate-local + @echo "uv run python -m src # 127.0.0.1:$(RUN_PORT), SESSION_TTL_SECONDS=$(SESSION_TTL_SECONDS)" + @$(LOCAL_ENV); APP_PORT=$(RUN_PORT) SESSION_TTL_SECONDS=$(SESSION_TTL_SECONDS) \ + uv run python -m src + +# relay и worker на хосте рядом с `make run` (брокер и хранилища — из +# compose); стоп — Ctrl+C. Сервисы compose relay и worker при этом лучше +# остановить: make stop-worker, docker compose stop relay +.PHONY: run-relay run-worker +run-relay: migrate-local + @$(LOCAL_ENV); uv run python -m src.relay + +run-worker: migrate-local + @$(WORKER_ENV); uv run python -m src.worker + +# миграции с хоста в PostgreSQL стенда (127.0.0.1:POSTGRES_HOST_PORT) +.PHONY: migrate-local +migrate-local: db-up + @echo "uv run alembic upgrade head # 127.0.0.1:$(POSTGRES_HOST_PORT)" + @$(LOCAL_ENV); uv run alembic upgrade head + +.PHONY: lint +lint: + uv run ruff format --check . + uv run ruff check . + +.PHONY: fmt +fmt: + uv run ruff format . + uv run ruff check --fix . + +# собственные тесты против запущенного стенда (BASE_URL, по умолчанию +# HAProxy рабочего стенда); EXPECT_REPLICAS — сколько реплик за BASE_URL +# (против `make run` — 1: тесты реплик пропускаются с причиной). +# Тесты с маркером fault сюда не входят, для них есть make failure-checks +EXPECT_REPLICAS ?= $(API_REPLICAS) +.PHONY: student-test +student-test: + BASE_URL=$(BASE_URL) EXPECT_REPLICAS=$(EXPECT_REPLICAS) uv run pytest + +# отдельный стенд из того же compose.yaml (свои PostgreSQL, Valkey, S3, +# volume, HAProxy и две реплики, свои пароли и ключи, без .env): сборка, +# миграции и bootstrap S3, make test и make student-test через его LB, +# test-failover, test-persistence, затем уборка при любом исходе. Рабочий +# стенд не трогается. $(PYTHON), а не uv run: uv повторно шлёт SIGINT, и +# Ctrl+C обрывал бы уборку +.PHONY: test-isolated +test-isolated: + $(PYTHON) student-tests/stand.py isolated + +# pytest -m fault на ещё одном одноразовом стенде: собственные хранилища и +# S3, уборщик с grace 25 с, несколько API с разными настройками (обычный, +# «тесный», «узкий по загрузкам») и hook student-tests/fault_hook.py. +# Дополнительные аргументы pytest — через FAULT_ARGS +.PHONY: failure-checks +failure-checks: + $(PYTHON) student-tests/stand.py failures $(FAULT_ARGS) + +# лаба 6: юнит-тесты модулей src (телеметрия) без стенда — секунды +.PHONY: unit-test +unit-test: + uv run pytest -m unit student-tests/unit + +# requirements.txt для образа — только из uv.lock, с хешами +.PHONY: requirements +requirements: + $(UV_EXPORT) --output-file requirements.txt + +.PHONY: requirements-check +requirements-check: + $(UV_EXPORT) | diff -u requirements.txt - && echo "requirements.txt matches uv.lock" + +# --- Docker и compose --------------------------------------------------------- + +# .env из шаблона со случайными паролями PostgreSQL и Valkey и ключами S3: +# в шаблоне они пустые, общего пароля стенда в git нет. Существующий .env +# не перезаписывается — дописываются только переменные шаблона, которых в +# нём нет (секреты — случайными). Печатаются только имена +.PHONY: env +env: + @$(PYTHON) scripts/lab6.py env + +.PHONY: docker-build +docker-build: + docker build -t $(IMAGE) . + +# весь стенд: сначала телеметрия (Collector, Prometheus, Loki, Tempo, +# Grafana — первые записи процессов уже есть куда отправить), затем +# хранилища и брокер -> migrate, s3-bootstrap -> api × API_REPLICAS, +# relay, worker, cleaner -> haproxy; --wait ждёт healthy. Если образ +# поменялся, compose пересоздаст все реплики сразу и API на это время +# пропадёт; плавная замена — через make rolling-update +TELEMETRY_SERVICES = otel-collector prometheus loki tempo grafana +.PHONY: up +up: env + $(DC) up -d --wait $(TELEMETRY_SERVICES) + $(DC) up -d --build --wait api relay worker cleaner haproxy + +# остановить контейнеры (SIGTERM); данные и контейнеры остаются. LB +# останавливается раньше реплик (depends_on); S3 — плавно, ~15 с +.PHONY: stop +stop: + $(DC) stop + +# удалить контейнеры; volume pgdata и s3data с данными остаются +# (удаление — wipe) +.PHONY: down +down: + $(DC) down + +# журнал всех реплик; префикс строки — имя контейнера реплики +.PHONY: logs +logs: + $(DC) logs -f api + +# журнал фона: relay и worker +.PHONY: logs-pipeline +logs-pipeline: + $(DC) logs -f relay worker + +# хранилища стенда с ожиданием healthcheck и bootstrap S3: для make run. +# --wait одноразовый сервис не ждёт — код bootstrap отдельно +.PHONY: db-up +db-up: env + $(DC) up -d --wait postgres valkey s3 rabbitmq + $(DC) up --no-deps --exit-code-from s3-bootstrap s3-bootstrap + +# снести стенд вместе с volume (данные пропадут); спрашивает подтверждение yes +.PHONY: wipe +wipe: + @read -p "Удалить все данные стенда (volume pgdata, s3data, rmqdata, promdata, lokidata, tempodata)? Введите yes: " answer; \ + if [ "$$answer" = "yes" ]; then \ + $(DC) down -v --remove-orphans; \ + else \ + echo "cancelled, nothing removed"; exit 1; \ + fi + +# --- Реплики за HAProxy (лаба 3) -------------------------------------------- + +# вернуть остановленные реплики (те же контейнеры и X-Instance-Id) и +# выставить их число API_REPLICAS; ждёт healthy +.PHONY: replicas +replicas: + $(DC) up -d --no-deps --no-recreate --wait --scale api=$(API_REPLICAS) api + +# вход одним синтетическим пользователем и серия GET /users/me с одним +# токеном через LB: X-Instance-Id каждого ответа и итог по репликам +.PHONY: instances +instances: + $(PYTHON) scripts/lab6.py instances --base-url "$(BASE_URL)" + +# таблица слотов backend api: IP реплики, статус (во время замены бывает +# DRAIN/MAINT) и счётчики запросов, сбоев соединения, retry и redispatch +.PHONY: lb-stats +lb-stats: + $(PYTHON) scripts/lab6.py lb-stats + +# make test-failover для каждой реплики по очереди с возвратом +# предыдущей (make replicas): какой контейнер остановлен, строка +# STOP_ONE_LOG и итог теста. STOP_MODE=kill — без graceful +STOP_MODE ?= stop +.PHONY: failover-each +failover-each: + $(PYTHON) scripts/lab6.py failover-each --base-url "$(BASE_URL)" \ + --replicas $(API_REPLICAS) --mode $(STOP_MODE) + +# выкатить текущий код без простоя: собрать образ, один раз прогнать +# миграции и менять реплики по одной, выводя старую через drain в LB +.PHONY: rolling-update +rolling-update: + API_REPLICAS=$(API_REPLICAS) scripts/rolling-update.sh + +# --- S3 и вложения (с лабы 4) ------------------------------------------------- + +# вложение через LB → остановка реплики, принявшей загрузку (stop-one.sh по +# её X-Instance-Id) → скачивание через другую, тот же SHA-256 → 404 +# постороннему → make replicas. STOP_MODE=kill — без graceful +.PHONY: attachment-failover +attachment-failover: + $(PYTHON) scripts/lab6.py attachment-failover --base-url "$(BASE_URL)" \ + --replicas $(API_REPLICAS) --mode $(STOP_MODE) + +# приватность bucket вне API: права ключей API, worker и уборщика (bootstrap в +# режиме check), анонимные запросы с хоста и из сети стенда, порты +# контейнера S3; затем уборка проверочных объектов. Код 1 при нарушении +.PHONY: s3-check +s3-check: + $(PYTHON) scripts/lab6.py s3-check + +# разовый проход уборщика незавершённых загрузок: 0 — проход дошёл до +# конца, 1 — прерван отказом, 2 — конфигурация +.PHONY: cleanup-once +cleanup-once: + $(DC) run --rm --no-deps cleaner --once + +# разовая сверка bucket и БД (трек 2) в контейнере уборщика. По умолчанию +# dry-run; APPLY=1 — исправить безопасное; MAX_CHANGES, STRATEGY=head, +# DEEP=1 (SHA-256 содержимого), RATE (объектов S3/с, 0 — без предела). +# Выход 0 — всё сошлось, 3 — есть неисправленные расхождения, 1 — проход +# не дошёл до конца, 2 — ошибка в настройках +APPLY ?= +MAX_CHANGES ?= +STRATEGY ?= +DEEP ?= +RATE ?= +.PHONY: reconcile +reconcile: + $(DC) run --rm --no-deps cleaner reconcile $(if $(APPLY),--apply,) \ + $(if $(MAX_CHANGES),--max-changes $(MAX_CHANGES),) \ + $(if $(STRATEGY),--strategy $(STRATEGY),) $(if $(DEEP),--deep,) \ + $(if $(RATE),--rate $(RATE),) + +# --- Брокер, relay, worker (лаба 5) ------------------------------------------- + +# worker стенда: остановить (шаг 2 сценария защиты) / снова запустить +.PHONY: stop-worker start-worker +stop-worker: + $(DC) stop worker + +start-worker: + $(DC) up -d --no-deps worker + +# сценарий защиты, шаги 2–3, одной командой: worker стоит → 202 → сообщение +# → 409 → scripts/restart.sh → worker → ready и thumbnail 256×160 +.PHONY: defense +defense: + $(PYTHON) scripts/lab6.py defense --base-url "$(BASE_URL)" + +# задания по состояниям и очередь брокера +.PHONY: pipeline-state +pipeline-state: + @$(PYTHON) scripts/lab6.py pipeline + +# реестр failed и replay в контейнере relay. Без APPLY=1 — только показ; +# с APPLY=1 нужен выбор (ATTACHMENT= или ERROR_CODE=...) и OPERATOR, +# REASON. Коды: 0 — готово, 3 — часть отказана, 1 — PostgreSQL, 2 — аргументы +ATTACHMENT ?= +ERROR_CODE ?= +LIMIT ?= 20 +OPERATOR ?= +REASON ?= +.PHONY: replay +replay: + $(DC) run --rm --no-deps relay replay $(if $(ATTACHMENT),--attachment $(ATTACHMENT),) \ + $(if $(ERROR_CODE),--error-code $(ERROR_CODE),) --limit $(LIMIT) \ + $(if $(APPLY),--apply --operator "$(OPERATOR)" --reason "$(REASON)",) + +# --- Наблюдаемость (лаба 6) --------------------------------------------------- + +# адрес Grafana стенда; пароль admin — GRAFANA_ADMIN_PASSWORD в .env +.PHONY: grafana +grafana: + @echo "http://127.0.0.1:$(GRAFANA_HOST_PORT)/d/messenger-lab6 (user admin, password: GRAFANA_ADMIN_PASSWORD in .env)" + +# журнал сервисов телеметрии +.PHONY: logs-telemetry +logs-telemetry: + $(DC) logs -f $(TELEMETRY_SERVICES) + +# связь сигналов на рабочем стенде (~1–2 мин): запрос со своим X-Request-Id +# → трасса в Tempo и запись в Loki с её trace_id; загрузка → трасса worker +# и запись «attachment processed»; метрики API и worker в Prometheus без +# запрещённых меток; пароля, токена, текста и имени файла нет ни в Loki, ни +# в трассах. Хранилища — через прокси источников Grafana. Код 1 при FAIL +.PHONY: telemetry-check +telemetry-check: + $(PYTHON) scripts/lab6.py telemetry-check --base-url "$(BASE_URL)" + +# уровень 4. Сквозная трасса одной загрузки с повтором (~1 мин): попытка 1 +# падает при остановленном S3, ready — со второй; в Tempo одна трасса +# API → relay (producer) → worker (consumer) → S3/PostgreSQL +.PHONY: trace-chain +trace-chain: + $(PYTHON) scripts/lab6.py trace-chain --base-url "$(BASE_URL)" + +PROMETHEUS_IMAGE = prom/prometheus:v3.15.1@sha256:fa3302279710be2f21a8301ec17a8b4f2301fd829bd113839b3b6b02b6f191a2 + +# юнит-тесты alert и recording rules без стенда: promtool из того же образа +.PHONY: alerts-test +alerts-test: + docker run --rm -v "$(CURDIR)/infra/otel/prometheus:/rules:ro" -w /rules \ + --entrypoint promtool $(PROMETHEUS_IMAGE) check rules rules.yml + docker run --rm -v "$(CURDIR)/infra/otel/prometheus:/rules:ro" -w /rules \ + --entrypoint promtool $(PROMETHEUS_IMAGE) test rules rules.test.yml + +# alerts на рабочем стенде искусственным отказом (~8–10 мин): worker +# остановлен → queue lag firing → resolved; таблица sessions под +# блокировкой → error rate firing → resolved +.PHONY: alerts-check +alerts-check: + $(PYTHON) scripts/lab6.py alerts-check --base-url "$(BASE_URL)" + +# Tempo остановлен под нагрузкой на OUTAGE_SECONDS (~3–4 мин): API и +# загрузки работают, память Collector ограничена, потери посчитаны +OUTAGE_SECONDS ?= 120 +.PHONY: telemetry-outage +telemetry-outage: + $(PYTHON) scripts/lab6.py telemetry-outage --base-url "$(BASE_URL)" \ + --seconds $(OUTAGE_SECONDS) + +# --- Нагрузочный стенд (лаба 6, трек 1 — цена наблюдаемости; профили лаб +# 3–5 сохранены: отказ и замена под нагрузкой, память загрузок, стоимость +# сверки, очередь под перегрузкой) -- +# Порядок работы — bench/RUNBOOK.md, правила — bench/AGENTS.md. Свой проект +# compose vlad-bench, рабочий стенд перед замером — make stop. + +TELEMETRY_LABEL ?= baseline +QUEUE_LABEL ?= baseline +FAILOVER_LABEL ?= baseline +ROLLOUT_LABEL ?= baseline +UPLOADS_LABEL ?= baseline +RECONCILE_LABEL ?= baseline +# серия трека 1 лабы 3 (сохраняется): a, b, db, ab, quick +SERIES ?= +SCALING_LABEL ?= +LABELS ?= +PLOTS ?= scaling +BENCH = $(CAFFEINATE) uv run python bench/run.py + +# лаба 6, трек 1: варианты телеметрии off, full, head, tail, balanced × 3 +# повтора при одной открытой нагрузке с редкими событиями (~50 мин); пишет +# evidence/telemetry-cost/<метка>/ +.PHONY: bench-telemetry +bench-telemetry: + $(BENCH) telemetry --label "$(TELEMETRY_LABEL)" + +# самопроверка профиля (~7 мин): все пять вариантов, один повтор, окна +# 5 + 20 + 12 с; метка quick-telemetry- в отчёт не идёт +.PHONY: bench-telemetry-quick +bench-telemetry-quick: + $(BENCH) telemetry-quick + +# лаба 5, трек 1: настройки concurrency/prefetch worker × классы изображений; +# ёмкость, ровная нагрузка, перегрузка при пределе незавершённых и +# восстановление; пишет evidence/queue/<метка>/ +.PHONY: bench-queue +bench-queue: + $(BENCH) queue --label "$(QUEUE_LABEL)" + +# самопроверка профиля очереди (~9 мин): c1p1 и c4p4 × классы s и x, один +# повтор, короткие окна; метка quick-queue- в отчёт не идёт +.PHONY: bench-queue-quick +bench-queue-quick: + $(BENCH) queue-quick + +# уровень 4 лабы 3: две реплики под постоянной нагрузкой, каждая в режимах +# stop, kill, pause с возвратом; пишет evidence/failover/<метка>/ +.PHONY: bench-failover +bench-failover: + $(BENCH) failover --label "$(FAILOVER_LABEL)" + +# проверка стенда отказа (~2 мин); метка quick-failover- в отчёт не идёт +.PHONY: bench-failover-quick +bench-failover-quick: + $(BENCH) failover-quick + +# уровень 4 лабы 3: поочерёдная замена (scripts/rolling-update.sh) под той +# же нагрузкой, с новой expand-ревизией; пишет evidence/rollout/<метка>/ +.PHONY: bench-rollout +bench-rollout: + $(BENCH) rollout --label "$(ROLLOUT_LABEL)" + +.PHONY: bench-rollout-quick +bench-rollout-quick: + $(BENCH) rollout-quick + +# лаба 4, уровень 4: сколько памяти занимает реплика, когда параллельно +# грузят 1, 10, 20 или 40 клиентов тела ~1 и ~10 MiB; сравниваются места +# по умолчанию и режим без лимита. Результат — evidence/uploads/<метка>/ +.PHONY: bench-uploads +bench-uploads: + $(BENCH) uploads --label "$(UPLOADS_LABEL)" + +# самопроверка профиля загрузок (~5 мин); метка quick-uploads- +.PHONY: bench-uploads-quick +bench-uploads-quick: + $(BENCH) uploads-quick + +# уровень 5, трек 2: стоимость сверки bucket и БД по размеру набора, +# стратегиям и под фоновой нагрузкой; пишет evidence/reconcile/<метка>/ +.PHONY: bench-reconcile +bench-reconcile: + $(BENCH) reconcile --label "$(RECONCILE_LABEL)" + +# самопроверка профиля сверки (~6 мин); метка quick-reconcile- +.PHONY: bench-reconcile-quick +bench-reconcile-quick: + $(BENCH) reconcile-quick + +# трек 1 лабы 3 (сохраняется для сравнения, в лабе 4 не обязателен): +# серия конфигураций, на каждую ячейку свежий стенд, открытая модель, +# поиск R*; пишет evidence/scaling/<метка>/. CONFIGS="4x1-pg0.5 4x1" — +# ячейки вместо профильных; RESUME=1 — продолжить прерванную метку +CONFIGS ?= +.PHONY: bench-scaling +bench-scaling: + @test -n "$(SERIES)" || (echo "usage: make bench-scaling SERIES=a|b|db|ab [SCALING_LABEL=...] [CONFIGS=...] [RESUME=1]"; exit 2) + $(BENCH) scaling --series "$(SERIES)" $(if $(SCALING_LABEL),--label "$(SCALING_LABEL)",) \ + $(if $(CONFIGS),--configs "$(CONFIGS)",) $(if $(RESUME),--resume,) + +# самопроверка серий (~5 мин): 1 × 1 и 2 × 1, короткие окна +.PHONY: bench-scaling-quick +bench-scaling-quick: + $(BENCH) scaling --series quick + +# сравнение двух меток серий (по общим конфигурациям); AA — метка того же +# кода, что BEFORE: уровень шума +.PHONY: bench-compare +bench-compare: + @test -n "$(BEFORE)" -a -n "$(AFTER)" || \ + (echo "usage: make bench-compare BEFORE=