30 lines
1.5 KiB
Markdown
30 lines
1.5 KiB
Markdown
# CLI incident toggle contract (CLI-OBS-12-001)
|
|
|
|
**Goal**: define a deterministic CLI flag and config surface to enter/exit incident mode, required by TELEMETRY-OBS-55-001/56-001.
|
|
|
|
## Flags and config
|
|
- CLI flag: `--incident-mode` (bool). Defaults to false.
|
|
- Config key: `Telemetry:Incident:Enabled` (bool) and `Telemetry:Incident:TTL` (TimeSpan).
|
|
- When both flag and config specified, flag wins (opt-in only; cannot disable if config enables and flag present).
|
|
|
|
## Effects when enabled
|
|
- Increase sampling rate ceiling to 100% for telemetry within the process.
|
|
- Add tag `incident=true` to logs/metrics/traces.
|
|
- Shorten exporter/reporting flush interval to 5s; disable external exporters when `Sealed=true`.
|
|
- Emit activation audit event `telemetry.incident.activated` with fields `{tenant, actor, source, expires_at}`.
|
|
|
|
## Persistence
|
|
- Incident flag runtime value stored in local state file `~/.stellaops/incident-mode.json` with fields `{enabled, set_at, expires_at, actor}` for offline continuity.
|
|
- File is tenant-scoped; permissions 0600.
|
|
|
|
## Expiry / TTL
|
|
- Default TTL: 30 minutes unless `Telemetry:Incident:TTL` provided.
|
|
- On expiry, emit `telemetry.incident.expired` audit event.
|
|
|
|
## Validation expectations
|
|
- CLI should refuse `--incident-mode` if `--sealed` is set and external exporters are configured (must drop exporters first).
|
|
- Unit tests to cover precedence (flag over config), TTL expiry, state file perms, and audit emissions.
|
|
|
|
## Provenance
|
|
- Authored 2025-11-20 to unblock PREP-CLI-OBS-12-001 and TELEMETRY-OBS-55-001.
|