Introduction
For best compatibility, we recommend using slf4j as your logging framework.
The guidance for log levels can be broken down by intended audience:
Trace
This level is for tracing program operation
Avoid stack traces at this level
Debug
Most standard exception logging should be done at this level
Stack traces should be at this level
Info
Issues that might be important, such as failing sources or an endpoint failing for an internal reason
Stack traces are acceptable at this level, but should be infrequent (do not log inside of a loop) and always include a descriptive message
Warn
Issues that a system administrator should resolve, like applications or features failing to install, or a configuration that should be changed
Warn messages should have information that can tell a system administrator how to recover from this condition
Logs should include a descriptive message that provides lots of context and information on how to resolve the issue, not just the stack trace
Avoid using this level for log messages spawned by external requests, unless absolutely necessary
Stack traces are acceptable at this level, but should be infrequent (do not log inside of a loop)
Error
Critical exceptions, such as errors that would keep the entire system from functioning correctly, or putting the system into a state where it is insecure
Error messages should have information that can tell a system administrator how to recover from this condition
Logs should include a descriptive message that provides lots of context and information on how to resolve the issue, not just the stack trace
Avoid using this level for log messages spawned by external requests
Stack traces are acceptable at this level, but should be infrequent (do not log inside of a loop)
General Guidelines
- do not log an exception and then re-throw exactly the same exception
- all exception stacktraces should be logged at some level
- in cases where errors are returned to clients, never return a stack trace to the remote client, generic error messages that do not expose the inner workings of the system should be returned
- be as specific as possible
- include state information such as variable values, especially when there's a probable cause for an exception
- if a logging message is expensive to generate and it will only be logged at the debug or lower level, wrap the logging statement in an
if(LOGGER.isDebugEnabled())block