references/observability.md

# Operational telemetry design

Start from service user journeys and incident questions. Define indicators, source, owner, retention, cardinality budget and sampling. Use trace propagation (`traceparent`), service identity/resource attributes, version/deployment, metrics for RED/USE symptoms, structured logs with trace/span IDs. Check semantic convention version and libraries before assuming exact field names.

Sensitive data: avoid payloads/tokens/user identifiers in logs and high-cardinality attributes; aggregate and sample intentionally. Validate end-to-end trace continuity and measure ingestion spend.

Official OpenTelemetry conventions: https://opentelemetry.io/docs/concepts/semantic-conventions/ and https://opentelemetry.io/docs/specs/semconv/