wiki:LoggingLevels
Last modified 6 years ago Last modified on 02/22/13 14:36:05

Logging Levels

PROPOSAL PROPOSAL PROPOSAL

The following is a PROPOSAL, it is NOT YET an agreement.

We use slf4j for our logging. This supports five log levels, in decreasing order or importance: error, warn, info, debug and trace.

error
Log at this level when there is a problem that the admin MUST take action over. For example, when the code discovers a problem that will lead to a loss of functionality, either for the end-user or the administrator.

The target audience of the message is the admin.

Example: a door failing to communicate with another dCache component, which is required to satisfy the user's request should be logged at error level.

warn
Log at this level when there's a problem that the administrator SHOULD take action over. For example, when a component discovers a problem that, while not affecting results, could result in degraded performance.

The warn level may also be used to record some security-related events; for example, that a user was denied access to dCache.

The target audience of the message is the admin.

info
Log at this level when a significant event has happened in the component's life-cycle. This is not used for reporting problems (see error or warn), it is for reporting things that are expected, under the circumstance.

The target audience of the message is the admin.

There are two requirements for logging at info level:

  1. the information is sufficiently useful that storing it in a log file makes sense,
  2. under normal conditions, these events occur very rarely (say, much less often than once an hour).

Example: pool-manager learns of a new pool.

debug
Log information at this level that would assist an admin in understanding dCache's behaviour; therefore, it is likely that this information is presented at decision points in the code. Note that this log level does NOT include information for diagnosing bugs in dCache.

The target audience of the message is the admin.

Example: that a download request was rejected because the file does not exist in dCache.

trace
Information useful for diagnosing bugs in dCache. The message is intended for developers with access to the source-code.

The target audience of the message is the developer: you can be as cryptic as you like!

Example: the arguments supplied to a method call.

Some general comments

All messages should describe the problem in precise language (should not be vague) but must be accurate (i.e., must say what it knows and not potentially lie). This is especially true for log messages targeted at the admin.

The same message appearing in multiple locations is a bad code smell. Either the message is too vague or the code isn't DRY.

If the target audience of a message is the admin then don't use terms they wouldn't understand. For example, don't use class, method or variable names. Enum constants may be OK, but be careful.