Logging Fundamentals
Logging is the application writing a record of what it is doing and what went wrong, so people can understand its behaviour after the fact. Good logs are the main window into a system running somewhere you cannot attach a debugger.
Levels
Use a logging library to get levels, timestamps and configurable output. The names vary slightly between libraries, but the idea is shared:
| Level | Use it for |
|---|---|
DEBUG |
Detail for developers; usually off in production |
INFO |
Normal, notable events: service started, order placed |
WARN |
Something unexpected that the system recovered from |
ERROR |
An operation failed and needs attention |
FATAL or CRITICAL |
The application cannot continue |
Pick the level by asking “who needs to see this, and when?”. If every request logs at ERROR, nobody will notice the real errors.
What makes a log line useful
- Say what happened and to what. “Payment failed for order 8812: card declined” beats “Error occurred”.
- Include identifiers such as order id, user id (not their name) and a correlation or request id that ties together all lines from one request.
- When logging an exception, include its message and stack trace as well as your own text.
- Prefer structured logging (key/value fields, often JSON) so tools can filter on fields. Plain text is fine for small systems if the format is consistent.
- Log at boundaries: incoming requests, calls to other systems, and decisions that change the flow.
What not to log
Never write passwords, tokens, API keys, full card numbers or other personal data to logs. Logs are copied, shipped to other systems and read by many people. See Secrets Management and Data Privacy Awareness.
Where logs go
Containers and cloud services expect the application to write to standard output and let the platform collect it; the twelve-factor link explains why. Logs may also be rotated, retained for a limited time and centralised in a log platform. Logging too much costs money and hides the signal, so log for a reader.
Logging is one part of Monitoring Concepts, and you read the result in Log Analysis.
Try it
Pick a small function in code you work on that handles a request or job. Add an INFO line when it starts and finishes, and a WARN or ERROR line with context when it fails. Trigger both paths and read the output. Could a colleague diagnose the failure from these lines alone, with no secrets exposed?
Common mistakes
- Logging everything at ERROR so real errors are not noticed.
- Vague lines such as "Error occurred" with no context.
- Writing secrets or personal data to logs.
- Logging an exception without its stack trace.
Check yourself
- What is the difference between WARN and ERROR?
- What should a useful log line include?
- Where should a containerised app write its logs?
- Which kinds of data must never be logged?