perf sentinelDocumentation / Design index
Design documentation index
Deep design documentation for perf-sentinel. These documents explain why each decision was made, not just what the code does. They are intended for contributors and maintainers who need to understand the rationale behind the implementation.
For user-facing documentation, see the Documentation index.
Table of contents
| Document | Topics |
|---|---|
| 01: Pipeline and Types | Pipeline vs hexagonal architecture, type chain, workspace split, deterministic output, quality gate |
| 02: Normalization | SQL state machine, HTTP normalizer, micro-optimizations (batch push, IN-list skip, hand-coded UUID) |
| 03: Correlation and Streaming | Batch HashMap grouping, LRU cache, ring buffer, TTL eviction, memory budget |
| 04: Detection | N+1, redundant and slow detection algorithms, borrowed keys, iterator-based window, cross-trace correlation |
| 05: GreenOps and Carbon | IIS formula, waste ratio dedup, CO2 conversion, SCI alignment |
| 06: Ingestion and Daemon | OTLP conversion, daemon event loop, sampling, security hardening, query API, Prometheus pg_stat |
| 07: CLI, Config and Release | Bench, query, report, diff subcommands. HTML dashboard sink, CSV export, deep-link hash, cheatsheet modal, vim-style tab shortcuts. Config parsing, release profile, distribution, source location |
| 08: Periodic Disclosure | Schema v1.0 determinism, G1/G2 granularity, collect-all validator, per-service attribution, daemon archive writer, disclose CLI dispatcher |
| 09: Carbon Attribution | Per-service energy + carbon at scoring time, region attribution, model precedence, aggregator runtime-vs-proxy branching |
| 10: Sigstore and SLSA | In-toto v1 predicate, Sigstore cosign signature flow, SLSA Build L3 build provenance, verify-hash chain, privacy on Rekor public |
Source file mapping
| Source File | Design Doc |
|---|---|
lib.rs | 01: Pipeline |
event.rs | 01: Pipeline |
pipeline.rs | 01: Pipeline |
quality_gate.rs | 01: Pipeline |
normalize/sql.rs | 02: Normalization |
normalize/http.rs | 02: Normalization |
normalize/mod.rs | 02: Normalization |
correlate/mod.rs | 03: Correlation |
correlate/window.rs | 03: Correlation |
detect/mod.rs | 04: Detection |
detect/n_plus_one.rs | 04: Detection |
detect/redundant.rs | 04: Detection |
detect/slow.rs | 04: Detection |
detect/correlate_cross.rs | 04: Detection |
detect/fanout.rs | 04: Detection |
detect/chatty.rs | 04: Detection |
detect/pool_saturation.rs | 04: Detection |
detect/serialized.rs | 04: Detection |
detect/sanitizer_aware.rs | 04: Detection |
detect/suggestions.rs | 04: Detection |
score/mod.rs | 05: GreenOps, 09: Carbon Attribution |
score/carbon.rs | 05: GreenOps |
score/carbon_compute.rs | 05: GreenOps, 09: Carbon Attribution |
score/region_breakdown.rs | 05: GreenOps |
ingest/mod.rs | 06: Ingestion |
ingest/json.rs | 06: Ingestion |
ingest/otlp.rs | 06: Ingestion |
ingest/pg_stat.rs | 06: Ingestion |
daemon/mod.rs | 06: Ingestion |
daemon/event_loop.rs | 06: Ingestion |
daemon/listeners.rs | 06: Ingestion |
daemon/tls.rs | 06: Ingestion |
daemon/json_socket.rs | 06: Ingestion |
daemon/sampling.rs | 06: Ingestion |
daemon/findings_store.rs | 06: Ingestion |
daemon/query_api.rs | 06: Ingestion |
config.rs | 07: CLI/Config, 08: Periodic Disclosure |
report/mod.rs, json.rs | 01: Pipeline |
report/metrics.rs | 06: Ingestion |
report/periodic/* | 08: Periodic Disclosure |
daemon/archive.rs | 08: Periodic Disclosure |
sentinel-cli/src/main.rs | 07: CLI/Config |
sentinel-cli/src/disclose.rs | 08: Periodic Disclosure |
sentinel-cli/src/tui.rs | 07: CLI/Config |