~lttng/lttng-ust/lttng-ust

Viewing all changes in revision 2963.

  • Committer: Mathieu Desnoyers
  • Author(s): Michael Jeanson
  • Date: 2022-01-24 20:28:46 UTC
  • Revision ID: git-v1:464c475658ae29039b3b9e769b5b02195688a94a
Add a Log4j 2.x Java agent

This adds a new agent to the LTTng-UST Java agents suite supporting the
Log4j 2.x logging backend.

This new agent can be enabled with 2 different configure options :

  1) Java agent with Log4j 2.x support:
  $ export CLASSPATH=/path/to/log4j-core.jar:/path/to/log4j-api.jar
  $ ./configure --enable-java-agent-log4j2

  2) Java agent with JUL + Log4j + Log4j2 support
  $ export CLASSPATH=/path/to/log4j-core.jar:/path/to/log4j-api.jar:/path/to/log4j-1.2.jar
  $ ./configure --enable-java-agent-all

The name of the new agent jar file is "lttng-ust-agent-log4j2.jar".
It will be installed in the arch-agnostic "$prefix/share/java" path
e.g: "/usr/share/java".

It uses the same jni library "liblttng-ust-log4j-jni.so" as the Log4j 1.x agent.

The agent was designed as a mostly drop-in replacement for applications
upgrading from Log4j 1.x to 2.x. It requires no modification to the
tracing configuration as it uses the same domain "-l / LOG4J" and the
loglevels integer representations are converted to the Log4j 1.x values
(excluding custom loglevels).

The recommended way to use this agent with Log4j 2.x is to add an
"Lttng" Appender with an arbiraty name and associate it with one or more
Logger using an AppenderRef.

For example, here is a basic log4j2 xml configuration that would send
all logging statements exlusively to an lttng appender:

    <?xml version="1.0" encoding="UTF-8"?>
    <Configuration status="WARN">
      <Appenders>
        <Lttng name="LTTNG"/>
      </Appenders>
      <Loggers>
        <Root level="all">
          <AppenderRef ref="LTTNG"/>
        </Root>
      </Loggers>
    </Configuration>

More examples can be found in the 'doc/examples' directory.

The implementation of the appender is based on this[1] great guide by
Keith D. Gregory which is so much more detailed than the official
documentation, my thanks to him.

[1] https://www.kdgregory.com/index.php?page=logging.log4j2Plugins

Change-Id: I34593c9a4c3140c8839cef8b58cc85745fe9f47f
Signed-off-by: Michael Jeanson <mjeanson@efficios.com>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>

expand all expand all

Show diffs side-by-side

added added

removed removed

Lines of Context: