Skip to content

fix: Log4j configurations and wording #11395

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

Merged
merged 6 commits into from
Nov 7, 2024
Merged

fix: Log4j configurations and wording #11395

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
4c06f9e
Fix Log4j configurations and improve wording
vy Sep 19, 2024
6400455
Remove Log4j schema
vy Oct 8, 2024
269ac21
Remove Log4j schema
vy Oct 8, 2024
35e3e61
Remove Log4j schema
vy Oct 8, 2024
b6521e2
Apply suggestions from code review
adinauer Nov 5, 2024
e17118d
Merge branch 'master' into log4j2-fixes
adinauer Nov 6, 2024
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
39 changes: 21 additions & 18 deletions docs/platforms/java/common/legacy/log4j2/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ An [updated Java SDK](/platforms/java/) SDK supersedes this deprecated version.

</Alert>

The `sentry-log4j2` library provides [Log4j 2.x](https://logging.apache.org/log4j/2.x/) support for Sentry via an [Appender](https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html) that sends logged exceptions to Sentry. Once this integration is configured you can _also_ use Sentry’s static API, [as shown on the usage page](/platforms/java/legacy/usage), in order to do things like record breadcrumbs, set the current user, or manually send events.
The `sentry-log4j2` library provides [Log4j 2](https://logging.apache.org/log4j/2.x/) support for Sentry via an [Appender](https://logging.apache.org/log4j/2.x/log4j-core/apidocs/org/apache/logging/log4j/core/Appender.html) that sends logged exceptions to Sentry. Once this integration is configured you can _also_ use Sentry’s static API, [as shown on the usage page](/platforms/java/legacy/usage), in order to do things like record breadcrumbs, set the current user, or manually send events.

The source can be found [on GitHub](https://github.com/getsentry/sentry-java/tree/master/sentry-log4j2).

Expand Down Expand Up @@ -41,23 +41,26 @@ Example configuration using the `log4j2.xml` format:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<configuration status="warn" packages="org.apache.logging.log4j.core,io.sentry.log4j2">
<appenders>
<Console name="Console" target="SYSTEM_OUT">
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n" />
</Console>

<Sentry name="Sentry" />
</appenders>

<loggers>
<root level="INFO">
<appender-ref ref="Console" />
<!-- Note that the Sentry logging threshold is overridden to the WARN level -->
<appender-ref ref="Sentry" level="WARN" />
</root>
</loggers>
</configuration>
<Configuration xmlns="https://logging.apache.org/xml/ns"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-2.xsd">

<Appenders>
<Console name="CONSOLE" target="SYSTEM_OUT">
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
</Console>
<Sentry name="SENTRY"/>
</Appenders>

<Loggers>
<Root level="INFO">
<AppenderRef ref="CONSOLE"/>
<!-- Note that the Sentry logging threshold is overridden to the WARN level -->
<AppenderRef ref="SENTRY" level="WARN"/>
</Root>
</Loggers>

</Configuration>
```

Next, **you’ll need to configure your DSN** (client key) and optionally other values such as `environment` and `release`. [See the configuration page](/platforms/java/legacy/configuration/#setting-the-dsn) for ways you can do this.
Expand Down
41 changes: 23 additions & 18 deletions docs/platforms/java/guides/spring-boot/logging-frameworks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,9 @@ However, if errors that may appear during startup should to be sent to Sentry, t

</Note>

### Log4j2
### Log4j 2

To use Sentry's Log4j2 integration in Spring Boot application, you must include a dependency to the `sentry-log4j2` module:
To use Sentry's Log4j 2 integration in Spring Boot application, you must include a dependency to the `sentry-log4j2` module:

```xml {tabTitle:Maven}
<dependency>
Expand All @@ -87,30 +87,35 @@ libraryDependencies += "io.sentry" % "sentry-log4j2" % "{{@inject packages.versi

For other dependency managers see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-log4j2).

Then [follow the guide on configuring Log4j2 with Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto-configure-log4j-for-logging) and configure `SentryAppender` in the `log4j2.xml` file:
Then [follow the guide on configuring Log4j 2 with Spring Boot](https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto-configure-log4j-for-logging) and configure `SentryAppender` in the `log4j2.xml` file:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" packages="org.apache.logging.log4j.core,io.sentry.log4j2">
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
</Console>
<Sentry name="Sentry" />
</Appenders>
<Loggers>
<Root level="info">
<AppenderRef ref="Sentry"/>
<AppenderRef ref="Console"/>
</Root>
</Loggers>
<Configuration xmlns="https://logging.apache.org/xml/ns"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-2.xsd">

<Appenders>
<Console name="CONSOLE" target="SYSTEM_OUT">
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
</Console>
<Sentry name="SENTRY"/>
</Appenders>

<Loggers>
<Root level="INFO">
<AppenderRef ref="CONSOLE"/>
<AppenderRef ref="SENTRY"/>
</Root>
</Loggers>

</Configuration>
```

<Note>

You do not need to configure your DSN in the Log4j2 configuration file since Sentry is configured from the Spring Boot integration.
You do not need to configure your DSN in the Log4j 2 configuration file since Sentry is configured from the Spring Boot integration.

However, if errors that may appear during startup should to be sent to Sentry, the DSN must be provided to <i>both</i> the Log4j2 and Spring Boot configurations.
However, if errors that may appear during startup should to be sent to Sentry, the DSN must be provided to <i>both</i> the Log4j 2 and Spring Boot configurations.

</Note>
2 changes: 1 addition & 1 deletion platform-includes/configuration/decluttering/java.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
When used together with one of the logging framework integrations, the Java SDK captures all error logs as events. If you see a particular kind of error very often that has a `logger` tag, you can ignore that particular logger entirely. For more information see our <Link to="/platforms/java/guides/logback/">Logback</Link> or <Link to="/platforms/java/guides/log4j2/">Log4j 2.x</Link> integration.
When used together with one of the logging framework integrations, the Java SDK captures all error logs as events. If you see a particular kind of error very often that has a `logger` tag, you can ignore that particular logger entirely. For more information see our <Link to="/platforms/java/guides/logback/">Logback</Link> or <Link to="/platforms/java/guides/log4j2/">Log4j 2</Link> integration.
46 changes: 23 additions & 23 deletions platform-includes/getting-started-config/java.log4j2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,36 +6,37 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se

</Note>


```xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn" packages="org.apache.logging.log4j.core,io.sentry.log4j2">
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
</Console>
<Sentry name="Sentry"
dsn="___PUBLIC_DSN___" />
</Appenders>
<Loggers>
<Root level="info">
<AppenderRef ref="Sentry"/>
<AppenderRef ref="Console"/>
</Root>
</Loggers>
<Configuration xmlns="https://logging.apache.org/xml/ns"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://logging.apache.org/xml/ns https://logging.apache.org/xml/ns/log4j-config-2.xsd">

<Appenders>
<Console name="CONSOLE" target="SYSTEM_OUT">
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
</Console>
<Sentry name="SENTRY" dsn="___PUBLIC_DSN___"/>
</Appenders>

<Loggers>
<Root level="INFO">
<AppenderRef ref="CONSOLE"/>
<AppenderRef ref="SENTRY" level="ERROR"/>
Copy link
Collaborator

@lbloder lbloder Oct 8, 2024

Choose a reason for hiding this comment

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

Is there a particular reason for adding the level here, compared to the original?
Do you want to highlight the possibility of overriding the level like in docs/platforms/java/common/legacy/log4j2/index.mdx? If so, I would suggest to also add a comment here, like in the mentioned file.

Copy link
Contributor Author

@vy vy Oct 8, 2024

Choose a reason for hiding this comment

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

@lbloder, earlier the snippet was as follows:

<Root level="info">
  <AppenderRef ref="Sentry"/>
  <AppenderRef ref="Console"/>
</Root>

Though this didn't capture the configuration stated at the beginning of the java.log4j2.mdx file:

The following example using the log4j2.xml format to configure a ConsoleAppender that logs to standard out at the INFO level, and a SentryAppender that logs to the Sentry server at the ERROR level.

That is, sending ERRORs (and of higher severity) to Sentry was misconfigured – I fixed it.

Do you want to highlight the possibility of overriding the level like in docs/platforms/java/common/legacy/log4j2/index.mdx...

I am not able to follow you. I fixed legacy/log4j2/index.mdx too, since that document was stating:

The following example configures a ConsoleAppender that logs to standard out at the INFO level and a SentryAppender that logs to the Sentry server at the WARN level.

Hence, AFAIC, all configurations now match what is stated to be expected from them.

Copy link
Collaborator

@lbloder lbloder Oct 8, 2024

Choose a reason for hiding this comment

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

@vy Sorry for the confusion.
Thank you, for fixing this, I just looked at the differences in the xml and thus overlooked the fact that the description was wrong in the first place.

I am not able to follow you. I fixed legacy/log4j2/index.mdx too, since that document was stating
I was referring to the inline comment above the AppenderRef that might be helpful for users copying the xml.
For example:

<Root level="info">
    <AppenderRef ref="CONSOLE"/>
		<!-- Note that the Sentry logging threshold is overridden to the ERROR level -->
    <AppenderRef ref="SENTRY" level="ERROR"/>
</Root>

</Root>
</Loggers>

</Configuration>
```

`SentryAppender` does not support Log4j2's [async mode](https://logging.apache.org/log4j/2.x/manual/async.html). The Sentry Java SDK itself is already asynchronous and does not perform any blocking operation on the calling thread.
`SentryAppender` does not support [Log4j's asynchronous loggers](https://logging.apache.org/log4j/2.x/manual/async.html). The Sentry Java SDK itself is already asynchronous and does not perform any blocking operation on the calling thread.

### DSN Configuration

Note that **you need to configure your DSN** (client key) only if you wish to initialize the SDK through the log4j2 integration. If you're planning to use `Sentry.init` to provide configuration, such as by using the `beforeSend` callback, you **should not** provide the DSN in both `Sentry.init` and the appender configuration; just leave it out of the appender configuration in this case.

Note that **you need to configure your DSN** (client key) only if you wish to initialize the SDK through the Log4j 2 integration. If you're planning to use `Sentry.init` to provide configuration, such as by using the `beforeSend` callback, you **should not** provide the DSN in both `Sentry.init` and the appender configuration; just leave it out of the appender configuration in this case.

```xml
<Sentry name="Sentry"
dsn="___PUBLIC_DSN___" />
<Sentry name="SENTRY" dsn="___PUBLIC_DSN___" />
```

If the DSN is not present in the `log4j2.xml` configuration, Sentry will attempt to read it from the system property `sentry.dsn`, environment variable `SENTRY_DSN` or the `dsn` property in `sentry.properties` file. [See the configuration page](/platforms/java/configuration/) for more details on external configuration.
Expand All @@ -59,9 +60,8 @@ Breadcrumbs are kept in memory (by default the last 100 records) and are sent wi
```xml
<!-- Setting minimumBreadcrumbLevel modifies the default minimum level to add breadcrumbs from INFO to DEBUG -->
<!-- Setting minimumEventLevel the default minimum level to capture an event from ERROR to WARN -->
<Sentry name="Sentry"
<Sentry name="SENTRY"
dsn="___PUBLIC_DSN___"
minimumBreadcrumbLevel="DEBUG"
minimumEventLevel="WARN"
/>
minimumEventLevel="WARN"/>
```
2 changes: 1 addition & 1 deletion public/_platforms/java.json
View file
Open in desktop

Large diffs are not rendered by default.

Loading