Skip to main content

​
Rules

​
Core rules

  • Write for humans first (machines second).
  • Always include context.
  • Be explicit about what failed.
  • Use consistent structure.
  • Match log level to intent.
  • Log once, at the right layer.
  • Never log secrets or PII.
  • Avoid logs that describe the obvious.
  • Log outcomes, not intentions.
  • Prefer facts over emotions.
  • Make logs searchable.
  • Use English and a neutral, professional tone.
Rule of thumb: If someone sees the log at 3 a.m., they should immediately know what happened, where, and why.

​
Logging structure

Consistency makes logs searchable and parseable. Recommended pattern 
<action> <result> (key=value, key=value)
Example 
Fetched player session successfully (playerId=9c1e..., durationMs=12)

​
Always include context

Context turns noise into signal. Include:
  • IDs (requestId, userId, orderId, correlationId)
  • Important parameters (never secrets)
  • System state if relevant
Good 
User authentication failed (userId=42, ip=192.168.1.10)
Bad 
Authentication failed

​
Be explicit about what failed

Avoid vague verbs like “error occurred”. Good 
Failed to parse JWT token (reason=invalid_signature)
Bad 
JWT error

​
Match log level to intent

Misused log levels destroy signal.
LevelWhen to use
TRACEVery detailed internal flow (almost never in prod)
DEBUGUseful for developers, disabled in prod
INFOExpected, important lifecycle events
WARNUnexpected but recoverable situations
ERRORFailed operation, user impact possible
FATALApp cannot continue

​
Log once, at the right layer

Do not log the same failure at every level of the stack. Rule
  • Log where you can add the most context.
  • Lower layers should throw, higher layers should log.

​
Never log secrets or PII

This includes:
  • Passwords
  • Tokens (JWT, API keys)
  • Session cookies
  • Personal data (unless legally approved)

​
Quick checklist before committing

Ask yourself:
  • Can I understand this without reading the code?
  • Does it include enough context?
  • Is the log level correct?
  • Would this help during an incident?
  • Is anything sensitive included?