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

• Ideally, exceptions should be handled in only one place
  • Unless clean up / rollback semantics are needed higher up the call stack
• Do not log an exception until it is handled
  • This prevents log leak / false logs when an error is actually recoverable
• Do not log an exception and then re-throw exactly the same exception
  • This floods the logs and makes troubleshooting harder
  • Instead of catching and rethrowing the same exception in order to log additional diagnostic info, attach the info to the exception itself by wrapping it (it will appear in the logs when the exception is handled, if appropriate)
• 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