Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix log4j2 appender docs #4985

Closed
wants to merge 5 commits into from
Closed

Fix log4j2 appender docs #4985

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7b71e0d
Fix log4j2 appender docs
jack-berg Dec 28, 2021
8ad58ea
PR feedback
jack-berg Dec 30, 2021
95b6717
Fix library-autoconfigure readme
jack-berg Dec 30, 2021
6fb47c4
PR feedback
jack-berg Jan 3, 2022
8d2bc2b
Update maven link for library-autoconfigure module
jack-berg Jan 3, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions instrumentation/log4j/log4j-appender-2.16/library/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# 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.

**Maven**

```xml
<dependencies>
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-log4j-appender-2.16</artifactId>
<version>{version}</version>
jack-berg marked this conversation as resolved.
Show resolved Hide resolved
<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>{version}</version>
</dependency>
</dependencies>
```

**Gradle**

```kotlin
dependencies {
runtimeOnly("io.opentelemetry.instrumentation:opentelemetry-log4j-appender-2.16:{version}")
// The SDK appender is required to configure the appender with the OpenTelemetry Log SDK
implementation("io.opentelemetry.instrumentation:opentelemetry-instrumentation-sdk-appender:{version}")
}
```

The following demonstrates how you might configure the appender in your `logback.xml` configuration:
jack-berg marked this conversation as resolved.
Show resolved Hide resolved

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="io.opentelemetry.instrumentation.log4j.appender.v2_16">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@open-telemetry/java-instrumentation-maintainers this is terrible package name, it will confuse the hell out of our users.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added this to Special Topics meeting agenda for tomorrow

<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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see any OpenTelemetryAppender in the example below. Maybe I don't know anything about log4j appenders, but I am confused here :)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OpenTelemetryAppender is the name given to the appender configured in the xml snippet above.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but this name is not present in the code. So how exactly do I "associate the OpenTelemetryAppender configured via log4j2.xml with a SdkLogEmitterProvider"? What if I use another name in log4j.xml, do I need to change my code somehow?


```
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`.
63 changes: 8 additions & 55 deletions ...og4j/log4j-context-data/log4j-context-data-2.16/library-autoconfigure/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# 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.

## Usage

To use it, add the module to your application's runtime classpath.

Expand All @@ -11,8 +14,8 @@ To use it, add the module to your application's runtime classpath.
<dependencies>
<dependency>
<groupId>io.opentelemetry.instrumentation</groupId>
<artifactId>opentelemetry-log4j-2.13.2</artifactId>
<version>0.17.0-alpha</version>
<artifactId>opentelemetry-log4j-context-data-2.16-autoconfigure</artifactId>
<version>{version}</version>
<scope>runtime</scope>
</dependency>
</dependencies>
Expand All @@ -22,12 +25,10 @@ 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-context-data-2.16-autoconfigure:{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).
Expand Down Expand Up @@ -63,51 +64,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`.