Skip to content

Application Logging Guidance

Logging is a fundamental aspect of software development and application management. It provides invaluable insight into an application's behavior and performance. Effective logging practices are essential for understanding how applications work, diagnosing problems, and ensuring a seamless user experience as applications become more complex, distributed and mission critical.

In a multi-process environment within a Docker container, ensuring that logs from all child processes are captured and directed to stdout/stderr can be challenging but is crucial for centralized log management.

End users can download application logs through the device's user interface. They will receive an archive file containing logs for all containers, with logs for each container's standard output (stdout) and standard error (stderr) streams separated. Additionally, the system can be configured to stream the logs to an external destination where stdout and stderr streams are merged.

Important

Apps must not log any form of confidential data under any circumstances.

Guidance of Log Levels

  • In general, the logging framework is organized by the following log levels, which are listed below in descending order of urgency or importance:
  • Fatal: This log level indicates that at least one system component is inoperative, causing a fatal error within the larger system.
  • Error: This log entry indicates that at least one system component is inoperable and is affecting the operability of other functions.
  • Warning: This log message indicates that an unexpected event has occurred in an application that may interrupt or delay other processes.
  • Info: This log level records an event that has occurred but does not appear to affect operations. These alerts can usually be ignored, provided the rest of the system continues to operate normally.
  • Debug: The Debug log captures relevant details of events that may be useful during software debugging or troubleshooting within the test environment.
  • Trace: This log level records the execution of code. It is considered an information message and does not require any action. However, it can be useful if the team needs full visibility within the application or a third-party library.
  • Log levels should be adjustable. If everything is running smoothly after the application is installed, the log levels should be lowered and only tracked when errors occur.
  • Log levels should be manually adjustable by the user.

Guidance for Functionality and Context

  • Detailed information about the cause of the error should be included in the error message. If there are error IDs, then there should be documentation that contains detailed information about the error (error ID, root cause, possible solutions).
  • If everything works fine, there should be no error messages, but possibly warnings. (Irrelevant/false errors make it difficult to analyses real errors).
  • A reasonable log rotation should be selected. Disk space is valuable space!
  • Logs should be broken up into smaller chunks, avoid creating huge log files.
  • Logs should be marked with the related date/time when naming the files during export.
  • At startup, log files should contain the "meta" information about the component/installation that generates the logs (application name, container name, app release, container version, time of creation...).
  • For multi-container applications; log files must be uniquely identified

Guidance for Formatting & Content Requirements

Logs should include the following information:

  • either as json or text
  • Time: in RFC3339 format, including milliseconds
  • Time: should be in UTC
  • Level: either lowercase or uppercase on of these (TRACE, DEBUG, INFO, WARN, ERROR, FATAL)
  • Source in [], language specific (Java: "class name"; Go: "component:file:line")
  • Message free text message
  • Structured arbitrary number of key/value pairs with "=" as separator; special characters are escaped, values with spaces are enclosed in "

as text:

2021-11-10T13:18:38.933Z WARN  [authservice:sqliteapplicationusersengine.go:116] This is a warning from business logic with ctx  X-Correlation-ID=din006f7-9b589683-9677-404c-be72-8988d08e950f key="escaping val\"u\\e"

as JSON:

{"level":"info","time":"2021-11-10T13:18:38.933Z","component":"module1", "message":"Hello World!", "key2":"abc"}

Guidance on Characters

  • Logs should not contain non-printable characters
  • Unicode characters should be avoided -> ASCII only
  • If Unicode is used, use UTF8 and please do not mix different UNICODE types.

Guidance for Logs, displayed Inside the Application

  • A functionality to clear the log messages is recommended for better debugging purposes (e.g. clearing log messages after triggering an error). If a log has been cleared, this should be indicated in the new log.
  • There should be a mechanism to store and archive old logs.