Documentation / Overview
Documentation index
This directory contains the user-facing documentation for perf-sentinel. For deep design rationale aimed at contributors, see the Design index sub-directory.
A French mirror of every document lives under FR/00-INDEX.
Getting started
| Document | Description |
|---|
| Architecture | Pipeline overview, module responsibilities, key types |
| Integration | Four deployment topologies (batch, sidecar, gateway, standalone) and quick starts |
| Instrumentation | Per-language OTLP setup: Java, Quarkus, .NET, Go, Python, Node.js, Rust |
| CI | CI mode, GitHub Actions / GitLab CI / Jenkins recipes, PR regression detection |
Reference
| Document | Description |
|---|
| Configuration | Full .perf-sentinel.toml reference (thresholds, detection, GreenOps, daemon) |
| CLI reference | Subcommand reference (analyze, watch, report, diff, query, ack, inspect, disclose, verify-hash) |
| Metrics | Prometheus metrics exposed by the daemon on /metrics |
| Query API | Daemon HTTP API (/api/findings, /api/correlations, /api/explain/{trace}, /api/status) |
| SARIF | SARIF v2.1.0 output format for IDE and GitHub Code Scanning integration |
| Schema | JSON Schema for the periodic disclosure report (perf-sentinel-report v1.0) |
Features
| Document | Description |
|---|
| HTML report | Self-contained HTML dashboard, live mode via --daemon-url, ack/revoke from the browser |
| Inspect (TUI) | Interactive TUI: Analyze/Inspect/Explain drill-down (analyze --tui, inspect, explain --tui), arrow or vim keys, ack/revoke |
| Acknowledgments | .perf-sentinel-acknowledgments.toml format, SHA-256 signatures, filtering rules |
| Ack workflow | End-to-end acknowledgment workflow across daemon API, CLI, TUI, and HTML report |
| Reporting | Periodic public disclosure via perf-sentinel disclose, schema versioning, hash verification |
Operations
| Document | Description |
|---|
| Helm deployment | Kubernetes deployment via the Helm chart, values reference, TLS, RBAC |
| Runbook | Incident runbook: symptom-driven troubleshooting for production deployments |
| Methodology | Calculation chain from traces to efficiency_score, energy_kwh, carbon_kgco2eq |
| Limitations | Known trade-offs, upstream constraints, detection boundaries |
Supply chain and release
| Document | Description |
|---|
| Supply chain | Build input pinning, Sigstore signing, SLSA provenance, verify-hash chain |
| Release procedure | End-to-end release procedure from 0.7.0 onwards, simulation-lab gate, Helm lockstep |
Sub-directories
| Directory | Contents |
|---|
| Design index | Deep design documentation (10 chapters), contributor-facing |
| FR/00-INDEX | French mirror of all documents |
ci-templates/ | CI snippet files referenced by CI.md |
schemas/ | JSON Schema and examples for the disclosure report |
diagrams/ | Architecture diagrams |
examples/ | Example configurations and outputs |
img/ | Generated terminal GIFs and PNGs (VHS tapes) |
perf sentinel