Logging Conventions

How we write logs that are clear, consistent, and incident-ready

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.

Level	When to use
TRACE	Very detailed internal flow (almost never in prod)
DEBUG	Useful for developers, disabled in prod
INFO	Expected, important lifecycle events
WARN	Unexpected but recoverable situations
ERROR	Failed operation, user impact possible
FATAL	App 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?