Polymarket Engine — Документация

Тема

CLAUDE.md — Observability section (draft) ​

Status: DRAFT. Operator to inline into CLAUDE.md when they commit their current WIP. This file lives in docs/operations/ to avoid trampling the operator's uncommitted CLAUDE.md changes.

Origin: OpenSpec change harden-ws-and-add-metrics Phase 4 §9.4. Companion change: add-bootstrap-shutdown-safety (FSM-Phase 1).

Suggested insert into CLAUDE.md (under a new "Observability" heading, between "Optional integrations" and "Multi-wallet + SQLite strategy config") ​

markdown
## Observability stack (ADR-035)

Prometheus + Alertmanager + Telegram digests live in
`docker-compose.bot.yml`. Pm-bot exposes `:9091/metrics` (scrape) and
`:9091/internal/alert-relay` (AM webhook forward to TG).

### Запуск
```bash
# Local-dev:
docker compose -f docker-compose.bot.yml up -d prometheus alertmanager

# VPS (after first deploy):
ssh deploy@204.168.229.194 \
  'docker compose -f ~/pm-backtest/instances/harvester-live/docker-compose.yml \
   up -d prometheus alertmanager'

# Smoke procedure: docs/operations/alerting-stack-smoke.md

14 правил alerting (10 critical / 4 warning) ​

Critical: BotDown, LifecycleHalted, KillSwitchTriggered, WsDisconnected, WsStaleMessages, UserWsParseError, OrphanOrdersAtShutdown, DailyPnlNearKillSwitch, NoOrderActivity, WsUnknownEventBurst.

Warning: OrderPostErrorRate, ReconciliationDrift, WsReconnectSpike, ScannerLoopLagHigh.

Per-alert diagnostics + acknowledge/silence procedures: docs/operations/alerting-runbook.md.

Telegram digests + alert-relay ​

  • BOT_TG_DIGEST_ENABLED=true (default false) — master switch
  • BOT_TG_BOT_TOKEN, BOT_TG_REPORTS_CHAT_ID — required when enabled
  • Fail-fast если enabled=true с пустым token/chat
  • Single TG-чат для critical/warning/info — severity prefix ([CRIT]/[WARN]/[INFO]) в тексте отличает уровни
  • Hourly @ ровно :00 UTC+3 (fixed offset, без DST drift)
  • Daily @ 00:00 UTC+3 — EOD summary с top winner/loser

Когда BOT_TG_DIGEST_ENABLED=false (default):

  • TG sender = None, digest task НЕ spawn'ится
  • /internal/alert-relay route НЕ монтируется
  • AM получит 404 на webhook — оператор видит в docker logs
  • Hot trading loop — bit-identical к pre-Phase-4

Cross-refs ​


---

## Also: update existing "Architecture Decision Records" table

Add row for ADR-035 between ADR-031 (currently last row in the
ACCEPTED block):

```markdown
| [adr-035-observability-and-ws-coverage](docs/adr/adr-035-observability-and-ws-coverage.md) | Observability stack: standalone `:9091/metrics`, AM→bot→TG webhook chain, UTC+3 digests, retention 7d, exposure-budget alert намеренно опущен; WS unknown-event hardening + strict user-channel parser + FSM-driven WsDriftSuspected halt | ACCEPTED |

Also: update "Environment" fail-fast policy footnote ​

Append BOT_TG_* to the conditional-required block — they are fail-fast only when BOT_TG_DIGEST_ENABLED=true:

markdown
**Phase 4 §10.5 — Telegram digest (conditional fail-fast):**
`BOT_TG_DIGEST_ENABLED=true` требует non-empty `BOT_TG_BOT_TOKEN` и
`BOT_TG_REPORTS_CHAT_ID` — panics с информативным сообщением при
старте если ровно один из них пуст. При `BOT_TG_DIGEST_ENABLED=false`
оба ignored, hot loop bit-identical.