Movses AslanyanandClaude Opus 5.5
44d7801617
Phase 4 records what was built, the two skipped Build steps (OTLP-logs experiment, LogQL test migration) and what carries forward. Phase 3 records its outcome, with the chaos-nightmare and blocking_event_loop criteria attested by the user. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
80 lines
5.4 KiB
Markdown
80 lines
5.4 KiB
Markdown
# Roadmap summary — all phases at a glance
|
||
|
||
*Part of `docs/roadmap/` — the one-page overview. Read [`intro.md`](intro.md)
|
||
first for platform/background context; read the individual `phase-N.md` file
|
||
for the phase you're actually working on. This file exists so an agent (or
|
||
you) can check overall status and sequencing without loading every phase's
|
||
full detail.*
|
||
|
||
Twelve phases (0 through 11 — Phase 0 has two halves, 0a and 0b). Each phase
|
||
file follows the same shape: **Status**, **Message** (what's done, notes,
|
||
warnings), **Time-box**, **Concepts**, **Resources**, **Build**, **Done when**.
|
||
|
||
## Status and focus
|
||
|
||
| Phase | File | Status | Focus | Time-box | Main output |
|
||
|---|---|---|---|---|---|
|
||
| 0a | [`phase-0.md`](phase-0.md) | Done | Integration test suite (agent, tests only) | 1 evening | Red suite + `RED-BASELINE.md` |
|
||
| 0b | [`phase-0.md`](phase-0.md) | Done | Base project implemented to green (second agent) | 1–2 evenings | Ledgerline running, list of frustrations |
|
||
| 1 | [`phase-1.md`](phase-1.md) | Done | Deployment: Compose + Traefik on a server | 1 evening | `https://ledgerline.vione.cloud` |
|
||
| 2 | [`phase-2.md`](phase-2.md) | Done | Concepts + first trace | 1 evening | One trace in Tempo |
|
||
| 3 | [`phase-3.md`](phase-3.md) | Done | Distributed tracing | 2–3 evenings | Connected trace across 7 services incl. the async hop |
|
||
| 4 | [`phase-4.md`](phase-4.md) | Done | Structured logs | 1–2 evenings | Two-way trace↔log correlation |
|
||
| 5 | [`phase-5.md`](phase-5.md) | In progress | Metrics | 2 evenings | RED per service, service map, exemplars |
|
||
| 6 | [`phase-6.md`](phase-6.md) | Not started | Dashboards as code | 2 evenings | `kubectl apply -k k8s/` restores all dashboards |
|
||
| 7 | [`phase-7.md`](phase-7.md) | Not started | k6 + percentiles | 1–2 evenings | Baseline vs degraded load profiles |
|
||
| 8 | [`phase-8.md`](phase-8.md) | Not started | SLO / error budget / RTO / RPO | 1–2 evenings | `docs/SLO.md` + burn-rate alerts |
|
||
| 9 | [`phase-9.md`](phase-9.md) | Not started | Bottleneck hunting | 2 evenings | `docs/INVESTIGATION.md` |
|
||
| 10 | [`phase-10.md`](phase-10.md) | Not started | Filebeat / Logstash / OTel judgment | 1–2 evenings | `docs/PIPELINE-CHOICES.md` |
|
||
| 11 | [`phase-11.md`](phase-11.md) | Not started | Delivery | 1 evening | README + rehearsed demo |
|
||
|
||
## What each phase is, in one line
|
||
|
||
- **0 — Build the base project, test-first.** Write the black-box test suite,
|
||
then implement the seven-service system against it as a frozen contract.
|
||
**Done** — see `phase-0.md` for the full implementation report.
|
||
- **1 — Deployment.** Put Ledgerline on a server with Docker Compose behind
|
||
Traefik and a Let's Encrypt certificate, served at a real domain. Plumbing
|
||
only — no telemetry, no app changes. **Done** — see `phase-1.md`.
|
||
- **2 — The model, and one signal end to end.** Learn the OTel API/SDK/Collector
|
||
split and the M.E.L.T. vocabulary; deploy the real Grafana-stack platform
|
||
(the mentor's Ansible stack, ported to k3s as `k8s/` — already deployed on
|
||
`falken`) and get one auto-instrumented trace into Tempo. **Done** — see
|
||
`phase-2.md` for what carries forward.
|
||
- **3 — Distributed tracing.** The heart of the task: auto- and
|
||
manual-instrument all seven services, and hand-propagate trace context
|
||
across the Redis Stream hop, which carries none by default. **Done** — see
|
||
`phase-3.md`.
|
||
- **4 — Structured logs, correlated to traces.** Replace prose logging with
|
||
structured events carrying a lowercase `trace_id`, so Loki and Tempo link
|
||
in both directions. **Done** — see `phase-4.md` (OTLP-logs experiment and the
|
||
LogQL test migration skipped).
|
||
- **5 — Metrics.** Instrument RED metrics per service, understand cardinality
|
||
limits, and route app metrics to Prometheus given Alloy rejects OTLP metrics
|
||
(404 on `/v1/metrics`). Tempo's metrics-generator already produces span metrics and the
|
||
service graph — don't duplicate it in the collector.
|
||
- **6 — Dashboards and alerts as code.** Generate dashboard JSON with the
|
||
Grafana Foundation SDK and ship it with the platform (`k8s/grafana/`), so
|
||
"destroy and recreate in seconds" is a real, repeatable command.
|
||
- **7 — Load testing with k6, and percentiles.** Learn why percentiles can't
|
||
be averaged, what coordinated omission is, and drive Ledgerline with
|
||
arrival-rate executors to get a clean before/after load profile.
|
||
- **8 — SLI, SLO, SLA, error budgets, RTO, RPO.** Define Ledgerline's SLIs and
|
||
SLOs from the Phase 7 baseline (not from thin air), write an error-budget
|
||
policy, and wire multi-burn-rate alerts.
|
||
- **9 — Bottleneck hunting (the capstone).** Given a random, undisclosed set
|
||
of chaos flags, find the pathologies from telemetry alone using a top-down,
|
||
hypothesis-driven method, and write it up as an incident doc.
|
||
- **10 — Tool-selection judgment.** Reason through Filebeat vs Logstash vs
|
||
OpenTelemetry on six concrete axes, using the platform's real second stack
|
||
(Filebeat → Logstash → Elasticsearch → Kibana) as the counterpoint.
|
||
- **11 — Package the delivery.** README, a rehearsed five-minute demo, the
|
||
written deliverables (`SLO.md`, `PIPELINE-CHOICES.md`, `INVESTIGATION.md`,
|
||
`CONCEPTS.md`), and an honest "what I'd do differently in production"
|
||
section.
|
||
|
||
## If you have to cut scope
|
||
|
||
Cut Phase 10's build (keep the writing) and Phase 7's soak test first. **Do not
|
||
cut Phase 9** — it's the only phase that proves you learned anything.
|