references/best-practices.md · 24000
ages
- Only scalar values (strings, numbers, booleans) are logged. No raw objects, large arrays, or full API response bodies
- Context is accumulated throughout the request lifecycle (e.g.,
cart_totaladded once calculated,payment_idadded later)
Business and trace context
- The "Who":
posthogDistinctId,org_id,account_tier, or equivalent - The "What":
order_id,transaction_id,feature_flag_variants, or equivalent - The "Where":
service.name,service.version,deployment.environmentset as OTel resource attributes - Trace IDs: OpenTelemetry
trace_idis attached so you can jump from logs to traces - Session IDs: PostHog
session_idis included to enable Session Replay linking
Levels and sampling
- Log levels are correct: INFO for request completion, WARN for retries or non-breaking issues, ERROR only if someone needs to act
- Health checks (
/healthz) and load balancer pings are excluded or sampled down - A sampling strategy is in place (or planned) for high-traffic services
- A
try/finallyor global error handler flushes log context if the process dies mid-request
Security and compliance
- No secrets: API keys, Bearer tokens, and passwords are scrubbed
- PII is masked: emails, physical addresses, and credit card numbers are hashed or removed per GDPR/HIPAA requirements
- Request/response bodies are not logged (to avoid capturing sensitive user data)
- Field names and value types are treated as a stable schema (changes are communicated)
- Consider enabling automatic PII scrubbing as a safety net for accidental leaks
- Link logs to Session Replays for full user context