Files
aevolution/docs/adr/0015-observability.md
T
dingoandClaude Opus 5.5 7aec68db8e Complete M7.8 operations endpoints and region server image
ADR-0066: evo-server --ops-listen serves /livez (loop responding, never
authority), /readyz (200 only while the host holds the lease with a
verified recovered head) and /metrics (Prometheus text: 30 fixed
series for readiness, phase, lease epoch/remaining, simulated/committed
ticks, commit lag, checkpoint age, tick debt, queue use and bounds, and
counters; the only labels are a 6-value phase and 4-value drop reason).

The dependency-free OpsServer runs on the host loop with no thread:
GET on exact paths, 405/404/400/431 responses, 8 connections with excess
refused on accept, 4 KiB requests, 1 s deadlines, 16 KiB responses.
HostStatus/phase types moved to the portable evo::ops library with a
Windows-tested renderer. evo-server now refuses to start without its
required identity and connection settings.

Adds the server-runtime Docker target (evo-server + pinned libpq,
UID 10001, no credentials), a CI server-image job with smoke script and
optional publishing, and a Kubernetes example outside Argo.

Validated: Windows CTest 59/59; Linux Debug/Release/clang-tidy/ASan
CTest 59/59; PostgreSQL suites under Release, clang-tidy and ASan with
real process probes; two ops mutations caught. Docker build/smoke and
Gitea CI not executed locally.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 23:09:28 -04:00

37 lines
1.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ADR-0015: Metrics outside authoritative state
## Status
Small proof boundary adopted; Prometheus/Grafana/Loki/Otel adapters proposed for M7–M8.
M7.8 (ADR-0066) implements the region server exposition with a tiny direct
responder and fixed-label metrics; client libraries remain unadopted.
## Context
Need tick/entity/recovery evidence without observer effects on decisions.
## Decision
Kernel exposes deterministic values; host measures monotonic duration and exports separately. Proof text sink reports tick/entity gauges and benchmark runtime; no HTTP needed. No entity/genome/account metric labels.
## Alternatives Considered
prometheus-cpp (MIT) provides client APIs; Otel C++ (Apache-2.0) adds metrics/logs/traces/exporter dependencies. Tiny direct exposition needs format tests.
## Benefits
Replay-safe instrumentation and replaceable exporter.
## Costs
Host aggregation, retention and cardinality budgets.
## Risks
Blocking observers, high-cardinality exhaustion and wall-time/logical-time confusion.
## Consequences
M7 adds tick histograms, checkpoint age, fencing/recovery/queue/persistence metrics. Biology flows when implemented. Compare binary/allocations/tail latency/drop behavior/portability; no noisy timing gates. [prometheus-cpp](https://github.com/jupp0r/prometheus-cpp), [Otel C++](https://github.com/open-telemetry/opentelemetry-cpp).