Files
aevolution/docs/adr/0015-observability.md
2026-10-08 12:08:53 -04:00

38 lines
1.4 KiB
Markdown
Raw Permalink 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.
[Reviewed]
# 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).