Skip to content

Latest commit

 

History

History
 
 

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 

Appender Instrumentation for Log4j2 version 2.17 and higher

This module provides a Log4j2 appender which forwards Log4j2 log events to the OpenTelemetry Log SDK.

Quickstart

Add these dependencies to your project

Replace OPENTELEMETRY_VERSION with the latest release.

For Maven, add to your pom.xml dependencies:

<dependencies>
  <dependency>
    <groupId>io.opentelemetry.instrumentation</groupId>
    <artifactId>opentelemetry-log4j-appender-2.17</artifactId>
    <version>OPENTELEMETRY_VERSION</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

For Gradle, add to your dependencies:

runtimeOnly("io.opentelemetry.instrumentation:opentelemetry-log4j-appender-2.17:OPENTELEMETRY_VERSION")

Usage

The following demonstrates how you might configure the appender in your log4j.xml configuration:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="io.opentelemetry.instrumentation.log4j.appender.v2_17">
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT">
      <PatternLayout
          pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} trace_id: %X{trace_id} span_id: %X{span_id} trace_flags: %X{trace_flags} - %msg%n"/>
    </Console>
    <OpenTelemetry name="OpenTelemetryAppender"/>
  </Appenders>
  <Loggers>
    <Root>
      <AppenderRef ref="OpenTelemetryAppender" level="All"/>
      <AppenderRef ref="Console" level="All"/>
    </Root>
  </Loggers>
</Configuration>

In this example Log4j2 log events will be sent to both the console appender and the OpenTelemetryAppender.

In order to function, OpenTelemetryAppender needs access to an OpenTelemetry instance. This must be set programmatically during application startup as follows:

import io.opentelemetry.instrumentation.log4j.appender.v2_17.OpenTelemetryAppender;
import io.opentelemetry.sdk.OpenTelemetrySdk;

public class Application {

  public static void main(String[] args) {
    OpenTelemetrySdk openTelemetrySdk = // Configure OpenTelemetrySdk

    // Find OpenTelemetryAppender in log4j configuration and install openTelemetrySdk
    OpenTelemetryAppender.install(openTelemetrySdk);

    // ... proceed with application
  }
}

Settings for the Log4j Appender

Setting can be configured as XML attributes, for example:

<Appenders>
  <OpenTelemetry name="OpenTelemetryAppender"
      captureMapMessageAttributes="true"
      captureMarkerAttribute="true"
      captureContextDataAttributes="*"
  />
</Appenders>

The available settings are:

XML Attribute Type Default Description
captureExperimentalAttributes Boolean false Enable the capture of experimental log attributes thread.name and thread.id.
captureMapMessageAttributes Boolean false Enable the capture of MapMessage attributes.
captureMarkerAttribute; Boolean false Enable the capture of Log4j markers as attributes.
captureContextDataAttributes String Comma separated list of context data attributes to capture. Use the wildcard character * to capture all attributes.
numLogsCapturedBeforeOtelInstall Integer 1000 Log telemetry is emitted after the initialization of the OpenTelemetry Log4j appender with an OpenTelemetry object. This setting allows you to modify the size of the cache used to replay the first logs.