Documentation / Overview
Documentation index
Perf Sentinel's user-facing documentation. For deep design rationale aimed at contributors, see the Design documentation.
Getting started
| Document | Description |
|---|
| Architecture | Pipeline overview, module responsibilities, key types |
| Instrumentation | Per-language OTLP setup: Java, Quarkus, .NET, Go, Python, Node.js, Rust, Ruby, PHP |
| CI | CI mode, GitHub Actions / GitLab CI / Jenkins recipes, PR regression detection |
Deployment
| Document | Description |
|---|
| Integration | Four deployment topologies (batch, sidecar, gateway, standalone) and quick starts |
| Helm deployment | Kubernetes deployment via the Helm chart, values reference, TLS, RBAC |
Reference
| Document | Description |
|---|
| Configuration | Full .perf-sentinel.toml reference (thresholds, detection, GreenOps, broker energy, 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.5) |
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 |
|---|
| Runbook | Incident runbook: symptom-driven troubleshooting for production deployments |
| Energy & carbon | Plain-language synthesis: how counts become kWh and gCO2, per configured option, with sources |
| Methodology | Calculation chain from traces to efficiency_score, energy_kwh, carbon_kgco2eq |
| Instance types | Every instance_type carrying an embedded power profile, with its idle and max wattage |
| Limitations | Known trade-offs, upstream constraints, detection boundaries |
Security, supply chain and release
| Document | Description |
|---|
| Security overview | Security review overview: network flows, access control, stored data, hardening, release integrity |
| 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 |
