Add a Log4j 2.x Java agent
authorMichael Jeanson <mjeanson@efficios.com>
Thu, 6 Jan 2022 19:36:46 +0000 (14:36 -0500)
committerMathieu Desnoyers <mathieu.desnoyers@efficios.com>
Mon, 21 Feb 2022 15:17:33 +0000 (10:17 -0500)
commit43c692e7a0f593984abffa5674c28e2c23c1e10a
treef9030e06d52c7ea98ba04cac3c2de51eb3b46246
parenta4b5af217b22f855342570ce11ddeea41661fd5d
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 the following configure option :

  $ export CLASSPATH=/path/to/log4j-core.jar:/path/to/log4j-api.jar
  $ ./configure --enable-java-agent-log4j2

This backport differs from the master branch for the
'--enable-java-agent-all' option won't select this new agent since we
wanted to avoid introducing a new dependency in existing configurations.

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>
38 files changed:
.gitignore
README.md
configure.ac
doc/examples/Makefile.am
doc/examples/java-jul/Makefile
doc/examples/java-log4j/Hello.java [deleted file]
doc/examples/java-log4j/HelloLog4j.java [new file with mode: 0644]
doc/examples/java-log4j/Makefile
doc/examples/java-log4j/run
doc/examples/java-log4j2-basic/.intree [new file with mode: 0644]
doc/examples/java-log4j2-basic/HelloLog4j2.java [new file with mode: 0644]
doc/examples/java-log4j2-basic/Makefile [new file with mode: 0644]
doc/examples/java-log4j2-basic/log4j2.xml [new file with mode: 0644]
doc/examples/java-log4j2-basic/run [new file with mode: 0755]
doc/examples/java-log4j2-ctx/HelloLog4j2Ctx.java [new file with mode: 0644]
doc/examples/java-log4j2-ctx/Makefile [new file with mode: 0644]
doc/examples/java-log4j2-ctx/log4j2.ctx1.xml [new file with mode: 0644]
doc/examples/java-log4j2-ctx/log4j2.ctx2.xml [new file with mode: 0644]
doc/examples/java-log4j2-ctx/run [new file with mode: 0755]
doc/examples/java-log4j2-prog/.intree [new file with mode: 0644]
doc/examples/java-log4j2-prog/HelloLog4j2Prog.java [new file with mode: 0644]
doc/examples/java-log4j2-prog/Makefile [new file with mode: 0644]
doc/examples/java-log4j2-prog/run [new file with mode: 0755]
doc/java-agent.txt
src/lib/lttng-ust-java-agent/java/Makefile.am
src/lib/lttng-ust-java-agent/java/lttng-ust-agent-all/Manifest.txt
src/lib/lttng-ust-java-agent/java/lttng-ust-agent-log4j2/Makefile.am [new file with mode: 0644]
src/lib/lttng-ust-java-agent/java/lttng-ust-agent-log4j2/Manifest.txt [new file with mode: 0644]
src/lib/lttng-ust-java-agent/java/lttng-ust-agent-log4j2/org/lttng/ust/agent/log4j2/LttngLog4j2Agent.java [new file with mode: 0644]
src/lib/lttng-ust-java-agent/java/lttng-ust-agent-log4j2/org/lttng/ust/agent/log4j2/LttngLog4j2Api.java [new file with mode: 0644]
src/lib/lttng-ust-java-agent/java/lttng-ust-agent-log4j2/org/lttng/ust/agent/log4j2/LttngLogAppender.java [new file with mode: 0644]
src/lib/lttng-ust-java-agent/jni/Makefile.am
src/lib/lttng-ust-java-agent/jni/log4j/Makefile.am
src/lib/lttng-ust-java-agent/jni/log4j/lttng_ust_log4j.c
src/lib/lttng-ust-java-agent/jni/log4j/lttng_ust_log4j.h [deleted file]
src/lib/lttng-ust-java-agent/jni/log4j/lttng_ust_log4j2.c [new file with mode: 0644]
src/lib/lttng-ust-java-agent/jni/log4j/lttng_ust_log4j_tp.c [new file with mode: 0644]
src/lib/lttng-ust-java-agent/jni/log4j/lttng_ust_log4j_tp.h [new file with mode: 0644]
This page took 0.02814 seconds and 4 git commands to generate.