| name | implementation-observability |
| description | Implement usage and cost accounting, privacy filtering, diagnostics, logs, traces, metrics, feature-evaluation evidence, health reporting, disk fallback, and update-check observation. Use when adding an event, sink, counter, profiler, diagnostic command, or operational alert without making observability a correctness dependency. |
Implementation Observability
Observe the semantic runtime without becoming its authority. Read observability-contract.md before defining events, attributes, counters, traces, buffers, disk fallback, diagnostics, or update health. Read the versioned event wire catalog and its event-wire diagram when implementing generated internal-event, experiment, authentication-context, or timestamp records. Use architecture.drawio to trace privacy filtering and sink failure.
Workflow
- Start from a canonical semantic event or explicit operational measurement.
- Classify fields by privacy, cardinality, source, and whether aggregation is sufficient.
- For local DEBUG diagnostics, prefer maximum safe evidence: stable stage and reason codes, bounded counts, booleans, classifications, correlation IDs, and durations. Never substitute payloads or exact secret-capable configuration merely because DEBUG was requested; attachment bytes, base64, source/storage paths, decoded content, data URLs, and provider bodies remain prohibited.
- Apply opt-out, essential-traffic, managed-policy, build, and sink kill-switch decisions before routing.
- Update authoritative local usage/cost counters separately from best-effort exporters.
- Bound queues, batches, retries, disk persistence, open spans, and shutdown flush.
- Verify that disabling or breaking every sink does not alter semantic events, permissions, transcript, side effects, or exit status.
Completion check
Satisfy all OBS-* rules and scenarios. Test privacy filtering including hostile
attachment failures, high-cardinality rejection, duplicate exposure, offline
disk fallback, process restart, queue overflow, stale spans, malformed sink
response, and shutdown timeout.
