logging-log4j-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache <ralph.go...@dslextreme.com>
Subject Re: Opinions or guidelines on what each logging level is for?
Date Thu, 02 Feb 2017 18:34:55 GMT
Here it is. As I recall I borrowed this from several sources but I cannot recall what they
were.

Message levels
Log4j defines five levels of logging messages, ranging from TRACE to FATAL. The guidelines
for their use are very vague and in the grand UNIX tradition mix severity of the message with
its granularity. The following summary defines the basic rules on when to use a specific level,
who the target audience is and how any message of the specified level will be interpreted.
Note that all events with level INFO or higher present an API-like contract of the system
from the integration point-of-view: if they change, third-party systems such as monitoring
may need to be updated to work correctly with the new system release. The message text on
these levels should be understandable to people with networking and systems administration
background, so any language assuming knowledge of programming in general, or Java in particular,
should be avoided if at all possible.
Messages on DEBUG and higher present are part of interface contract with support entities,
e.g. if they are changed operator and troubleshooting manuals, as well as knowledge-base systems
may need to be updated to correctly interpret the information conveyed. On the DEBUG level,
messages may assume a slight level of familiarity with general programming concepts. Terminology
specific to any programming language should be avoided if possible.
FATAL
This should generally only be used for recording a failure that prevents the system starting,
i.e. the system is completely unusable. It is also possible that errors during operation will
also render the system unusable, but typically these will be identified as java.lang.Error
instances (such as an OutOfMemoryError), and hence we will not likely catch them, since catching
Throwable should only be done in very special cases.
ERROR
Records that something went wrong, i.e. some sort of failure occurred, and either:
The system was not able to recover from the error, or
The system was able to recover, but at the expense of losing some information or failing to
honour a request.
This should be immediately brought to the attention of an operator. Or to rephrase it, if
your error does not need immediate investigation by an operator, then it isn’t an error.
To permit monitoring tools to watch the log files for ERRORs and WARNings is crucial that:
These get logged
Sufficient information is provided to identify the cause of the problem
The logging is done in a standard way, which lends itself to automatic monitoring.
For example, if the error is caused by a configuration failure, the configuration filename
should be provided (especially if you have more than one file, yuck), as well as the property
causing the problem.
WARN
A WARN message records that something in the system was not as expected. It is not an error,
i.e. it is not preventing correct operation of the system or any part of it, but it is still
an indicator that something is wrong with the system that the operator should be aware of,
and may wish to investigate. This level may be used for errors in user-supplied information.
INFO
INFO priority messages are intended to show what’s going on in the system, at a broad-brush
level. INFO messages do not indicate that something’s amiss (use WARN or ERROR for that),
and the system should be able to run at full speed in production with INFO level logging.
The following types of message are probably appropriate at INFO level: <System component>
successfully initialised <Transaction type> transaction started, member: <member
number>, amount: <amount> <Transaction type> transaction completed, txNo: <transaction
number>, member: <member number>, amount: <amount>, result: <result code>
DEBUG
DEBUG messages are intended to help isolate a problem in a running system, by showing the
code that is executed, and the context information used during that execution. In many cases,
it is that context information that is most important, so you should take pains to make the
context as useful as possible. For example, the message ‘doTransaction() started’ says
nothing about which merchant the transaction is for, the type of transaction, the amount,
or anything else that might help us to relate this to a transaction that failed. Using Log4J’s
ThreadContext there is a common mechanism provided for thread-based (effectively request-based)
context (things like session IDs, transaction IDs etc.), so if some of the context in your
message should be common to all log messages for this request, set it in the context (and
make sure your PatternLayout can display it). In normal operation, a production system would
not be expected to run at DEBUG level. However, if there is an occasional problem being experienced,
DEBUG logging may be enabled for an extended period, so it’s important that the overhead
of this is not too high (up to 25% is perhaps OK).
TRACE
This is the fine-grained diagnostic level, serving for events which indicate internal state
transitions in full detail. Events on this level are not reported, but have to be explicitly
enabled and may be collected for support purposes.
Placement, amount and contents of these events is completely at the discretion of development
engineers. These events are completely release-specific, may change even between minor releases.
Examples of events reported at this level would be method entry and exit, possibly including
detailed input arguments, and dumps of internal data as it is being modified.
Primary audience of these events are senior support personnel and development engineers diagnosing
operational irregularities which relate directly to code structure, mainly offline after being
captured on a live system.



> On Feb 2, 2017, at 12:30 AM, Apache <ralph.goers@dslextreme.com> wrote:
> 
> I have some guidelines on a wiki for work. I will forward them when I get home.
> 
> Sent from my iPad
> 
> On Feb 1, 2017, at 8:29 PM, Matt Sicker <boards@gmail.com <mailto:boards@gmail.com>>
wrote:
> 
>> I had a meeting at work recently where a small debate was brought up as to what sorts
of things to log at each logging level. I had my own opinion about it, of course, but I noticed
that there are brief notes in the javadocs about each level (going back in the git logs, it
look like Ralph wrote those notes almost 6 years ago!) and that's about it when it comes to
any sort of specifics.
>> 
>> Does anyone have some more elaborations on why you'd use each level? Or some more
concrete differences between, for example, error/warn and debug/trace? Perhaps some examples
reflecting how you've used it in the past or even custom logging levels you've added?
>> 
>> In a related idea, I'm kind of thinking that a general page about logging concepts
may be useful for the manual, so I'd like to gather some opinions on said topics first.
>> 
>> -- 
>> Matt Sicker <boards@gmail.com <mailto:boards@gmail.com>>


Mime
View raw message