Update log4j instrumentation docs (#4915)

* Update log4j instrumentation docs for 1.10.0 release * More log4j doc changes for 0.10.0 * Updates for #4937 * Fix log4j documentation * Update instrumentation/log4j/log4j-2.16/library/README.md Co-authored-by: jack-berg <[email protected]>
open-telemetry · Jan 5, 2022 · 1d453de · 1d453de
1 parent e08ed9d
commit 1d453de
Show file tree

Hide file tree

Showing 3 changed files with 89 additions and 62 deletions.
diff --git a/docs/standalone-library-instrumentation.md b/docs/standalone-library-instrumentation.md
@@ -12,7 +12,8 @@ that can be used if you prefer that over using the Java agent:
 * [Guava](../instrumentation/guava-10.0/library)
 * [JDBC](../instrumentation/jdbc/library)
 * [Lettuce](../instrumentation/lettuce/lettuce-5.1/library)
-* [Log4j](../instrumentation/log4j/log4j-2.13.2/library)
+* [Log4j appender](../instrumentation/log4j/log4j-2.16/library)
+* [Log4j thread context](../instrumentation/log4j/log4j-2.16/library-autoconfigure)
 * [Logback](../instrumentation/logback-1.0/library)
 * [MongoDB Driver](../instrumentation/mongo/mongo-3.1/library)
 * [OkHttp](../instrumentation/okhttp/okhttp-3.0/library)

diff --git a/instrumentation/log4j/log4j-appender-2.16/library/README.md b/instrumentation/log4j/log4j-appender-2.16/library/README.md
@@ -0,0 +1,78 @@
+# Log4j2 Appender
+
+This module provides a Log4j2 [appender](https://logging.apache.org/log4j/2.x/manual/appenders.html)
+which forwards Log4j2 log events to
+the [OpenTelemetry Log SDK](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk/logs).
+
+To use it, add the following modules to your application's classpath.
+
+Replace `OPENTELEMETRY_VERSION` with the latest
+stable [release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation).
+
+**Maven**
+
+```xml
+
+<dependencies>
+  <dependency>
+    <groupId>io.opentelemetry.instrumentation</groupId>
+    <artifactId>opentelemetry-log4j-2.16</artifactId>
+    <version>OPENTELEMETRY_VERSION</version>
+    <scope>runtime</scope>
+  </dependency>
+  <dependency>
+    <!-- The SDK appender is required to configure the appender with the OpenTelemetry Log SDK -->
+    <groupId>io.opentelemetry.instrumentation</groupId>
+    <artifactId>opentelemetry-instrumentation-sdk-appender</artifactId>
+    <version>OPENTELEMETRY_VERSION</version>
+  </dependency>
+</dependencies>
+```
+
+**Gradle**
+
+```kotlin
+dependencies {
+  runtimeOnly("io.opentelemetry.instrumentation:opentelemetry-log4j-2.16:OPENTELEMETRY_VERSION")
+  // The SDK appender is required to configure the appender with the OpenTelemetry Log SDK
+  implementation("io.opentelemetry.instrumentation:opentelemetry-instrumentation-sdk-appender:OPENTELEMETRY_VERSION")
+}
+```
+
+The following demonstrates how you might configure the appender in your `log4j.xml` configuration:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Configuration status="WARN" packages="io.opentelemetry.instrumentation.log4j.v2_16">
+  <Appenders>
+    <Console name="Console" target="SYSTEM_OUT">
+      <PatternLayout
+          pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} traceId: %X{trace_id} spanId: %X{span_id} 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>
+```
+
+Next, associate the `OpenTelemetryAppender` configured via `log4j2.xml` with
+a `SdkLogEmitterProvider` in your application:
+
+```
+SdkLogEmitterProvider logEmitterProvider =
+  SdkLogEmitterProvider.builder()
+    .setResource(Resource.create(...))
+    .addLogProcessor(...)
+    .build();
+GlobalLogEmitterProvider.set(DelegatingLogEmitterProvider.from(logEmitterProvider));
+```
+
+In this example Log4j2 log events will be sent to both the console appender and
+the `OpenTelemetryAppender`, which will drop the logs until `GlobalLogEmitterProvider.set(..)` is
+called. Once initialized, logs will be emitted to a `LogEmitter` obtained from
+the `SdkLogEmitterProvider`.
diff --git a/...og4j/log4j-context-data/log4j-context-data-2.16/library-autoconfigure/README.md b/...og4j/log4j-context-data/log4j-context-data-2.16/library-autoconfigure/README.md
@@ -1,18 +1,22 @@
-# Log4j 2 Integration
+# Log4j2 Autoconfigure Integration
 
-This module provides Log4j2 extensions related to OpenTelemetry.
+This module provides a Log4j2 `ContextDataProvider` that injects trace context from active spans
+into log context.
 
 To use it, add the module to your application's runtime classpath.
 
+Replace `OPENTELEMETRY_VERSION` with the latest
+stable [release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation).
+
 **Maven**
 
 ```xml
 
 <dependencies>
   <dependency>
     <groupId>io.opentelemetry.instrumentation</groupId>
-    <artifactId>opentelemetry-log4j-2.13.2</artifactId>
-    <version>0.17.0-alpha</version>
+    <artifactId>opentelemetry-log4j-2.16-autoconfigure</artifactId>
+    <version>OPENTELEMETRY_VERSION</version>
     <scope>runtime</scope>
   </dependency>
 </dependencies>
@@ -22,22 +26,14 @@ To use it, add the module to your application's runtime classpath.
 
 ```kotlin
 dependencies {
-  runtimeOnly("io.opentelemetry.instrumentation:opentelemetry-log4j-2.13.2:0.17.0-alpha")
+  runtimeOnly("io.opentelemetry.instrumentation:opentelemetry-log4j-2.16-autoconfigure:OPENTELEMETRY_VERSION")
 }
 ```
 
-## OpenTelemetry Context Data Provider
-
 `OpenTelemetryContextDataProvider` implements the Log4j2 `ContextDataProvider` SPI, and injects the
 trace ID and span ID from an active span into
 Log4j's [context data](https://logging.apache.org/log4j/2.x/manual/thread-context.html).
 
-**Note**: Depending on your application, you may run into
-a [critical bug](https://issues.apache.org/jira/browse/LOG4J2-2838)
-with Log4j 2.13.2. If log messages show a `NullPointerException` when adding this instrumentation,
-please update to 2.13.3 or higher. The only change between 2.13.2 and 2.13.3 is the fix to this
-issue.
-
 Log4j will automatically pick up the integration when you include this module. The following keys
 will be added to the context when a log statement is made when a span is active:
 
@@ -63,51 +59,3 @@ You can use these keys when defining an appender in your `log4j.xml` configurati
   </Loggers>
 </Configuration>
 ```
-
-## OpenTelemetry Appender
-
-`OpenTelemetryAppender` is a
-Log4j2 [appender](https://logging.apache.org/log4j/2.x/manual/appenders.html) that can be used to
-forward log events to
-the [OpenTelemetry Log SDK](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk/logs)
-.
-
-The following demonstrates how you might configure the appender in your `log4j.xml` configuration:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<Configuration status="WARN" packages="io.opentelemetry.instrumentation.log4j.v2_16">
-  <Appenders>
-    <Console name="Console" target="SYSTEM_OUT">
-      <PatternLayout
-          pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} traceId: %X{trace_id} spanId: %X{span_id} 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>
-```
-
-Next, associate the `OpenTelemetryAppender` with a `SdkLogEmitterProvider` in your application:
-
-```
-SdkLogEmitterProvider logEmitterProvider =
-  SdkLogEmitterProvider.builder()
-    .setResource(Resource.create(...))
-    .addLogProcessor(...)
-    .build();
-OpenTelemetryLog4j.initialize(logEmitterProvider);
-```
-
-**Note:** In order to initialize the `OpenTelemetryAppender` your application must depend on the
-OpenTelemetry log sdk (`io.opentelemetry:opentelemetry-sdk-logs`).
-
-In this example Log4j2 logs will be sent to both the console appender and
-the `OpenTelemetryAppender`, which will drop the logs until `OpenTelemetryLog4j.initialize(..)` is
-called. Once initialized, logs will be emitted to a `LogEmitter` obtained from
-the `SdkLogEmitterProvider`.