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.
1---2name: implementation-observability3description: 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.4---56# Implementation Observability78Observe the semantic runtime without becoming its authority. Read [observability-contract.md](references/observability-contract.md) before defining events, attributes, counters, traces, buffers, disk fallback, diagnostics, or update health. Read the [versioned event wire catalog](references/event-wire-catalog.md) and its [event-wire diagram](assets/event-wire.drawio) when implementing generated internal-event, experiment, authentication-context, or timestamp records. Use [architecture.drawio](assets/architecture.drawio) to trace privacy filtering and sink failure.910## Workflow11121. Start from a canonical semantic event or explicit operational measurement.132. Classify fields by privacy, cardinality, source, and whether aggregation is sufficient.143. 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.154. Apply opt-out, essential-traffic, managed-policy, build, and sink kill-switch decisions before routing.165. Update authoritative local usage/cost counters separately from best-effort exporters.176. Bound queues, batches, retries, disk persistence, open spans, and shutdown flush.187. Verify that disabling or breaking every sink does not alter semantic events, permissions, transcript, side effects, or exit status.1920## Completion check2122Satisfy all `OBS-*` rules and scenarios. Test privacy filtering including hostile23attachment failures, high-cardinality rejection, duplicate exposure, offline24disk fallback, process restart, queue overflow, stale spans, malformed sink25response, and shutdown timeout.
greenpau