observability-and-instrumentation

Emit structured fields instead of plain strings, include a correlation or request id, and use consistent levels: debug for local detail, info for lifecycle events, warn for recoverable risk, error for failures. Never log secrets, tokens, or full request bodies without explicit redaction.

Track low-cardinality, aggregatable signals: counters for requests, failures, and retries; histograms for latency and queue wait; gauges for active workers or open connections. Avoid labels like user email, raw URLs, or unbounded error text that break aggregation.

Generate or accept the id at the trust boundary, then pass it through logs, trace spans, job payloads, and outbound provider calls when safe. Never use it for authentication, authorization, or tenant proof, and do not trust arbitrary client-supplied ids for security decisions.

Treat PII as sensitive by default and prefer stable opaque IDs over emails, names, or phone numbers. Redact before writing logs, traces, metrics, or audit records; if redaction behavior is unknown, mark it unknown rather than logging raw data.

Skip instrumentation when no operator question exists for the signal, such as pure UI copy changes or local-only refactors with no runtime impact. Prefer a few useful, verifiable signals over noisy volume that future maintainers cannot interpret.