Emits allowlisted structured fields, redacts secrets and PII, uses stable event names and correlation ids, and never logs raw request bodies.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Application logs are structured events with an allowlist of field names. Secrets, credentials, and personal data are redacted or hashed before emit. Event names are stable strings, not interpolated sentences. Every request-scoped event carries a correlation id that matches the trace. Raw request and response bodies are not logged.
Scope
- Field allowlist, redaction, event naming, correlation id, body prohibition, log access, and retention alignment for application logs from backend services.
- Debug logs in production-like environments.
- Handoff to erasure workflows when a log store is a personal-data system.
Outside this block
- Span attribute policy for distributed traces, except that correlation ids must match.
- Metrics label cardinality.
Contract
- Emitters may include only allowlisted keys; unknown keys are dropped or fail CI schema checks.
- Password, token, authorization header, cookie, and listed PII fields are redacted or replaced with a keyed hash before the log sink.
- Event name is a dotted constant from a registry; free-text messages may not include user-supplied strings that duplicate PII.
- Correlation id is present on request-scoped events and equals the trace identifier used for outbound calls.
- Request and response bodies, multipart files, and query strings that contain PII are not logged even at debug.
- Log stores used for operations honor erasure tickets for fields that remain directly identifying; hashed subject ids are documented as reversible or not.
Implementation guidance
- Follow the OWASP logging cheat sheet for not recording secrets, then add a project allowlist so new fields need review.
- Provide a typed logger;
log.info(obj)of an ORM entity is forbidden.
Failure handling
- Redaction failure (serializer dumps extra keys) drops the event or ships a redaction-error stub, never the raw object.
- Missing correlation id at a worker boundary creates a new id and records parent-missing, rather than logging the whole job payload to compensate.
- Debug level in production still applies the same allowlist.
Verification and operations
- Measure dropped-unknown-key rate, redaction-error stubs, events missing correlation id, and access reviews of log stores.
- Inject a canary secret in a test request and prove it never appears in the sink.
- Prove with tests that a password reset event does not include the raw token.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.