feat(P10): observability expansion — metrics + security headers (REQ-159)

New metrics:
- orca_jobs_running / orca_jobs_failed / orca_jobs_complete (gauges)
- orca_audit_chain_head (gauge, chain integrity)
- orca_drift_events_total, orca_ssh_errors_total (counters)
- orca_txn_apply_total, orca_txn_rollback_total (counters)
- orca_acl_denials_total (counter)

Security headers on metrics + healthz endpoints:
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY

New file: docs/metrics.md (Prometheus reference + scrape config)

---ci---
project: orca
phase: 10
milestone: v0.13
status: complete
requirements:
  covered: [159]
---/ci---
This commit is contained in:
Jon Chery
2026-08-10 13:44:04 +00:00
parent 531b36924c
commit ed91d68fbf
4 changed files with 158 additions and 108 deletions
+52
View File
@@ -0,0 +1,52 @@
# Orca Metrics Reference
Orca exposes Prometheus text-exposition metrics at `/metrics` on the
metrics endpoint (default `:9100`, configurable via `--addr`).
## Running the metrics endpoint
```sh
orca metrics --addr :9100
```
## Prometheus scrape config
```yaml
scrape_configs:
- job_name: orca
static_configs:
- targets: ['localhost:9100']
scrape_interval: 15s
```
## Metric reference
| Metric | Type | Description |
|--------|------|-------------|
| `nodes_total` | Gauge | Total number of registered nodes |
| `allocs_total` | Gauge | Total number of job allocations |
| `orca_jobs_by_state{state}` | Gauge | Jobs grouped by status (running, complete, failed, etc.) |
| `orca_audit_chain_head` | Gauge | Audit chain integrity (1 = chain head verified, 0 = error) |
## Counter metrics (incremented by CLI operations)
The following counters are incremented during normal operations and
are available when the metrics endpoint polls the DB:
| Metric | Type | Description |
|--------|------|-------------|
| `orca_drift_events_total` | Counter | Total drift events detected |
| `orca_ssh_errors_total` | Counter | Total SSH connection/exec errors |
| `orca_txn_apply_total` | Counter | Total transaction applies |
| `orca_txn_rollback_total` | Counter | Total transaction rollbacks |
| `orca_acl_denials_total` | Counter | Total ACL denials (enforce mode) |
## Security headers
The metrics endpoint sets the following security headers on all responses:
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
## Health check
The endpoint also exposes `/healthz` returning `200 ok` for liveness probes.