Lookups

Log4j Core provides a flexible and extensible property substitution system.

Property substitution system
Figure 1. Property substitution system

The property substitution system is composed of these elements:

  • A string interpolation engine (StrSubstitutor) that evaluates ${...} expressions. These expressions can contain recursive expressions and default values.

    See property substitution for more details.

  • The Interpolator that evaluates simple ${name} expressions.

    The Interpolator has two functions:

    • If name does not contain a colon : character, the Interpolator uses the Properties configuration element to resolve its value.

    • If name is of the form prefix:key, the Interpolator delegates the lookup to a StrLookup associated with prefix and falls back to evaluating ${key} if the lookup was not successful.

  • A set of StrLookup plugins, each one associated with a prefix, which retrieve data from external sources.

StrLookup is a simple map-like interface. The main difference between a map and StrLookup is that the latter can compute the value of a key dynamically in a global context or in the context of log event.

Common concerns

Evaluation contexts

Each lookup has an associated prefix, and Log4j can evaluate it in one of the following ways:

Global context

In a global context Log4j evaluates ${prefix:key} expressions by calling lookup("key") on the lookup associated to prefix. The result of this call only takes into account the global state of the system.

The global context is used to expand the attributes of a configuration file.

Log event context

In the context of a log event event, Log4j evaluates ${prefix:key} expressions by calling lookup(event, "key") on the lookup associated to prefix. The result of this call might take into account the contents of the log event, besides the global state of the system.

Some configuration attributes (e.g.,