Custom Log Levels

Defining Custom Log Levels in Code

Log4J 2 supports custom log levels. Custom log levels can be defined in code
or in configuration. To define a custom log level in code, use the
Level.forName() method. This method creates a new
level for the specified name. After a log level is defined you can log
messages at this level by calling the Logger.log() method and passing
the custom log level:

When defining a custom log level, the intLevel parameter (550 and 350 in the example above) determines
where the custom level exists in relation to the standard levels built-in to Log4J 2.
For reference, the table below shows the intLevel of the built-in log levels.

Standard log levels built-in to Log4J

Standard Level

intLevel

OFF

0

FATAL

100

ERROR

200

WARN

300

INFO

400

DEBUG

500

TRACE

600

ALL

Integer.MAX_VALUE

Defining Custom Log Levels in Configuration

Custom log levels can also be defined in configuration.
This is convenient for using a custom level in a logger filter
or an appender filter. Similar to defining log levels in code,
a custom level must be defined first, before it can be used.
If a logger or appender is configured with an undefined level,
that logger or appender will be invalid and will not process any log events.

The standard Logger interface cannot provide convenience methods for
custom levels, but the next few sections introduce a code generation tool
to create loggers that aim to make custom levels as easy to use
as built-in levels.

Adding or Replacing Log Levels

We assume that most users want to add custom level methods to the Logger interface,
in addition to the existing trace(), debug(), info(), ... methods for the built-in log levels.

There is another use case, Domain Specific Language loggers, where we want to replace
the existing trace(), debug(), info(), ... methods with all-custom methods.

For example, for medical devices we could have only critical(), warning(),
and advisory() methods.
Another example could be a game that has only defcon1(), defcon2(),
and defcon3() levels.

If it were possible to hide existing log levels, users could customize the
Logger interface to match their requirements. Some people may not want to
have a FATAL or a TRACE level, for example. They would like to be able to
create a custom Logger that only has debug(), info(), warn() and error() methods.

Generating Source Code for a Custom Logger Wrapper

Common Log4J usage is to get an instance of the Logger interface from the
LogManager and call the methods on this interface.
However, the custom log Levels are not known in advance, so Log4J cannot provide
an interface with convenience methods for these custom log Levels.

To solve this, Log4J ships with a tool that generates source code for a
Logger wrapper. The generated wrapper class has convenience methods for each
custom log level, making custom levels just as easy to use as the built-in levels.

There are two flavors of wrappers: ones that extend the Logger
API (adding methods to the built-in levels) and ones that customize
the Logger API (replacing the built-in methods).

When generating the source code for a wrapper class, you need to specify:

the fully qualified name of the class to generate

the list of custom levels to support and their intLevel relative strength

whether to extend Logger (and keep the existing built-in methods)
or have only methods for the custom log levels

You would then include the generated source code in the project
where you want to use custom log levels.

Example Usage of a Generated Logger Wrapper

Here is an example of how one would use a generated logger wrapper with
custom levels DIAG, NOTICE and VERBOSE:

This will generate source code for a logger wrapper that has the convenience methods
for the built-in levels as well as the specified custom levels. The tool prints the
generated source code to the console.
By appending " > filename" the output can be redirected to a file.

NOTE: Prior to log4j-2.9, this tool was an inner class Generate$ExtendedLogger.
Under the bash shell on Unix/Mac/Linux the dollar character $ needs to be escaped, so the class name should
be between single quotes 'org.apache.logging.log4j.core.tools.Generate$ExtendedLogger’.

Generating Custom Loggers

Use the following command to generate a logger wrapper that hides the built-in levels and has only custom levels:

This will generate source code for a logger wrapper that only has convenience
methods for the specified custom levels, not for the built-in levels.
The tool prints the generated source code to the console.
By appending " > filename" the output can be redirected to a file.

NOTE: Prior to log4j-2.9, this tool was an inner class Generate$ExtendedLogger.
Under the bash shell on Unix/Mac/Linux the dollar character $ needs to be escaped, so the class name should
be between single quotes 'org.apache.logging.log4j.core.tools.Generate$CustomLogger’.