Lookups

containerId

containerName

imageId

imageName

shortContainerId

shortImageId

Exception

Level

Logger

Marker

Message

ThreadId

ThreadName

Timestamp

version

runtime

vm

os

locale

hw

Attribute

accountName

clusterName

containerId

containerName

host

hostIp

imageId

imageName

labels

labels.app

labels.podTemplateHash

masterUrl

namespaceId

namespaceName

podId

podIp

podName

${main:0}

--file

${main:1}

foo.txt

${main:2}

--verbose

${main:3}

-x

${main:4}

bar

${main:\--file}

foo.txt

${main:\-x}

bar

${main:bar}

null

Example usage:

[source,xml] ---- <File name="Application" fileName="application.log"> <PatternLayout header="File: ${main:--file}"> <Pattern>%d %m%n</Pattern> </PatternLayout> </File> ----

[#MapLookup] == Map Lookup

The MapLookup serves several purposes.

1. Provide the base for Properties declared in the configuration file. 2. Retrieve values from MapMessages in LogEvents. 3. Retrieve values set with MapLookup.setMainArguments(String[)]

The first item simply means that the MapLookup is used to substitute properties that are defined in the configuration file. These variables are specified without a prefix - e.g. ${name}. The second usage allows a value from the current MapMessage, if one is part of the current log event, to be substituted. In the example below the RoutingAppender will use a different RollingFileAppender for each unique value of the key named "type" in the MapMessage. Note that when used this way a value for "type" should be declared in the properties declaration to provide a default value in case the message is not a MapMessage or the MapMessage does not contain the key. See the Property Substitution section of the Configuration page for information on how to set the default values.

[source,xml] ---- <Routing name="Routing"> <Routes pattern="{map:type}"> <Route> <RollingFile name="Rolling-${map:type}" fileName="${filename}" filePattern="target/rolling1/test1-${map:type}.%i.log.gz"> <PatternLayout> <pattern>%d %p %c{1.} [%t] %m%n</pattern> </PatternLayout> <SizeBasedTriggeringPolicy size="500" /> </RollingFile> </Route> </Routes> </Routing> ----

The marker lookup allows you to use markers in interesting configurations like a routing appender. Consider the following YAML configuration and code that logs to different files based on markers:

[source,yaml] ---- Configuration: status: debug

Appenders: Console: RandomAccessFile: - name: SQL_APPENDER fileName: logs/sql.log PatternLayout: Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n" - name: PAYLOAD_APPENDER fileName: logs/payload.log PatternLayout: Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n" - name: PERFORMANCE_APPENDER fileName: logs/performance.log PatternLayout: Pattern: "%d{ISO8601_BASIC} %-5level %logger{1} %X %msg%n"

Routing: name: ROUTING_APPENDER Routes: pattern: "{marker:}" Route: - key: PERFORMANCE ref: PERFORMANCE_APPENDER - key: PAYLOAD ref: PAYLOAD_APPENDER - key: SQL ref: SQL_APPENDER

Loggers: Root: level: trace AppenderRef: - ref: ROUTING_APPENDER ----

[source,java] ---- public static final Marker SQL = MarkerFactory.getMarker("SQL"); public static final Marker PAYLOAD = MarkerFactory.getMarker("PAYLOAD"); public static final Marker PERFORMANCE = MarkerFactory.getMarker("PERFORMANCE");

final Logger logger = LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME);

logger.info(SQL, "Message in Sql.log"); logger.info(PAYLOAD, "Message in Payload.log"); logger.info(PERFORMANCE, "Message in Performance.log"); ----

Note the key part of the configuration is pattern: "{marker:}"`. This will produce three log files, each with a log event for a specific marker. Log4j will route the log event with the `SQL` marker to `sql.log`, the log event with the `PAYLOAD` marker to `payload.log`, and so on.

You can use the notation `"${marker:name}"` and `"{marker:name}" to check for the existence of a marker where name is the marker name. If the marker exists, the expression returns the name, otherwise null.

[#StructuredDataLookup] == Structured Data Lookup

The StructuredDataLookup is very similar to the MapLookup in that it will retrieve values from StructuredDataMessages. In addition to the Map values it will also return the name portion of the id (not including the enterprise number) and the type field. The main difference between the example below and the example for MapMessage is that the "type" is an attribute of the StructuredDataMessage while "type" would have to be an item in the Map in a MapMessage.

[source,xml] ---- <Routing name="Routing"> <Routes pattern="{sd:type}"> <Route> <RollingFile name="Rolling-${sd:type}" fileName="${filename}" filePattern="target/rolling1/test1-${sd:type}.%i.log.gz"> <PatternLayout> <pattern>%d %p %c{1.} [%t] %m%n</pattern> </PatternLayout> <SizeBasedTriggeringPolicy size="500" /> </RollingFile> </Route> </Routes> </Routing> ----

[#SystemPropertiesLookup] == System Properties Lookup

As it is quite common to define values inside and outside the application by using System Properties, it is only natural that they should be accessible via a Lookup. As system properties are often defined outside the application it would be quite common to see something like:

[source,xml] ---- <Appenders> <File name="ApplicationLog" fileName="${sys:logPath}/app.log"/> </Appenders> ----

This lookup also supports default value syntax. In the sample below, when the `logPath` system property is undefined, the default value `/var/logs` is used:

[source,xml] ---- <Appenders> <File name="ApplicationLog" fileName="${sys:logPath:-/var/logs}/app.log"/> </Appenders> ----

[#UpperLookup] == Upper Lookup

The LowerLookup converts the passed in argument to upper case. Presumably the value will be the result of a nested lookup.

[source,xml] ---- <File name="Application" fileName="application.log"> <PatternLayout> <pattern>%d %p %c{1.} [%t] {upper:{${spring:spring.application.name}} %m%n</pattern> </PatternLayout> </File> ----

[#WebLookup] == Web Lookup

The WebLookup allows applications to retrieve variables that are associated with the ServletContext. In addition to being able to retrieve various fields in the ServletContext, WebLookup supports looking up values stored as attributes or configured as initialization parameters. The following table lists various keys that can be retrieved:

[cols="1m,4"]

Any other key names specified will first be checked to see if a ServletContext attribute exists with that name and then will be checked to see if an initialization parameter of that name exists. If the key is located then the corresponding value will be returned.

[source,xml] ---- <Appenders> <File name="ApplicationLog" fileName="${web:rootDir}/app.log"/> </Appenders> ----

=== Request lookups and asynchronous calls

Servlet 3.0 supports asynchronous calls, by default the request tracking - and therefore request related lookups, will not work. To make it work you can extract the servlet context attribute log4j.requestExecutor which is a BiConsumer<ServletRequest, Runnable> and call it passing the correct request and task to execute synchronously. During this task execution the lookups will be set up properly:

[source,java] ---- @GET // example using JAX-RS asynchronous feature backed by servlet AsyncContext public void get(@Suspended AsyncResponse response, @Context ServletContext context, @Context ServletRequest request) { final BiConsumer<ServletRequest, Runnable> log4jWrapper = (BiConsumer<ServletRequest, Runnable>) context.getAttribute("log4j.requestExecutor"); myThreadPool.submit) → log4jWrapper.accept(request, () → response.resume(doInternalGet(); } ----