implementation-observability

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

1. Start from a canonical semantic event or explicit operational measurement.
2. Classify fields by privacy, cardinality, source, and whether aggregation is sufficient.
3. 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.
4. Apply opt-out, essential-traffic, managed-policy, build, and sink kill-switch decisions before routing.
5. Update authoritative local usage/cost counters separately from best-effort exporters.
6. Bound queues, batches, retries, disk persistence, open spans, and shutdown flush.
7. 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.