Skip to content

Commit 11dd086

Browse files
lbloderlbloder
authored
Improve Logs documentation (#15670)
1 parent 07357f4 commit 11dd086

File tree

21 files changed

+262
-81
lines changed

21 files changed

+262
-81
lines changed

‎docs/platforms/java/guides/spring-boot/logging-frameworks/index.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
title: Logging Framework Integrations
3+
sidebar_order: 6
4+
description: "Learn more about using one of our logging integrations with Sentry Spring Boot."
5+
---
6+
7+
## Supported Logging Frameworks
8+
9+
Sentry provides integrations for the following logging frameworks with Spring Boot:
10+
11+
<PageGrid />

‎docs/platforms/java/guides/spring-boot/logging-frameworks/log4j2.mdx‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Log4j 2 Integration
3+
description: "Learn how to use Sentry's Log4j 2 integration with Spring Boot."
4+
---
5+
6+
For the best experience, we recommend using Sentry's Spring Boot integration with the Log4j 2 logging framework integration as they work together seamlessly.
7+
8+
<Alert level="warning" title="Logs over Breadcrumbs">
9+
10+
By default this integration captures logs as breadcrumbs and error events (great for error context!). But if you need to search and query your logs across your entire application, we recommend enabling the new logs feature. Logs at or above the `minimumLevel` are automatically sent as Sentry Logs when enabled.
11+
12+
</Alert>
13+
14+
## Installation
15+
16+
To use Sentry's Log4j 2 integration in Spring Boot application, you must include a dependency to the `sentry-log4j2` module:
17+
18+
```xml {tabTitle:Maven}
19+
<dependency>
20+
<groupId>io.sentry</groupId>
21+
<artifactId>sentry-log4j2</artifactId>
22+
<version>{{@inject packages.version('sentry.java.log4j2', '5.1.1') }}</version>
23+
</dependency>
24+
```
25+
26+
```groovy {tabTitle:Gradle}
27+
implementation 'io.sentry:sentry-log4j2:{{@inject packages.version('sentry.java.log4j2', '5.1.1') }}'
28+
```
29+
30+
```scala {tabTitle: SBT}
31+
libraryDependencies += "io.sentry" % "sentry-log4j2" % "{{@inject packages.version('sentry.java.log4j2', '5.1.1') }}"
32+
```
33+
34+
For other dependency managers see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-log4j2).
35+
36+
## Configuration
37+
38+
### Spring Boot Configuration
39+
40+
To send logs to Sentry and have them show up in the Logs section, you need to enable the feature:
41+
42+
```properties
43+
sentry.logs.enabled=true
44+
```
45+
46+
### XML Configuration
47+
48+
[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:
49+
50+
```xml
51+
<?xml version="1.0" encoding="UTF-8"?>
52+
<Configuration>
53+
54+
<Appenders>
55+
<Console name="CONSOLE" target="SYSTEM_OUT">
56+
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
57+
</Console>
58+
<Sentry name="SENTRY" minimumLevel="DEBUG" />
59+
</Appenders>
60+
61+
<Loggers>
62+
<Root level="INFO">
63+
<AppenderRef ref="CONSOLE"/>
64+
<AppenderRef ref="SENTRY"/>
65+
</Root>
66+
</Loggers>
67+
68+
</Configuration>
69+
```
70+
71+
<Alert>
72+
73+
You do not need to configure your DSN in the Log4j 2 configuration file since Sentry is configured from the Spring Boot integration.
74+
75+
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.
76+
77+
</Alert>
78+
79+
## Mapped Diagnostic Context (MDC)
80+
81+
Starting with Sentry Java SDK version 8.24.0, you can use the <PlatformLink to="/configuration/options/#contextTags">`contextTags`</PlatformLink> option to include specific properties from the Mapped Diagnostic Context (MDC) as attributes on log entries sent to Sentry.

docs/platforms/java/guides/spring-boot/logging-frameworks.mdx renamed to docs/platforms/java/guides/spring-boot/logging-frameworks/logback.mdx

Lines changed: 26 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
11
---
2-
title: Logging Framework Integrations
3-
sidebar_order: 6
4-
description: "Learn more about using one of our logging integrations with Sentry Spring Boot."
2+
title: Logback Integration
3+
description: "Learn how to use Sentry's Logback integration with Spring Boot."
54
---
65

7-
For the best experience, we recommend using Sentry's Spring Boot integration with one of the logging framework integrations as they work together seamlessly.
6+
For the best experience, we recommend using Sentry's Spring Boot integration with the Logback logging framework integration as they work together seamlessly.
87

9-
### Logback
8+
<Alert level="warning" title="Logs over Breadcrumbs">
9+
10+
By default this integration captures logs as breadcrumbs and error events (great for error context!). But if you need to search and query your logs across your entire application, we recommend enabling the new logs feature. Logs at or above the `sentry.logging.minimum-level` are automatically sent as Sentry Logs when enabled.
11+
12+
</Alert>
13+
14+
## Installation
1015

1116
To use Sentry Logback integration in Spring Boot application you must include a dependency to the `sentry-logback` module, then Sentry's Spring Boot Starter will auto-configure `SentryAppender`:
1217

@@ -22,6 +27,16 @@ To use Sentry Logback integration in Spring Boot application you must include a
2227
implementation 'io.sentry:sentry-logback:{{@inject packages.version('sentry.java.logback', '4.2.0') }}'
2328
```
2429

30+
## Configuration
31+
32+
### Spring Boot Configuration
33+
34+
To send logs to Sentry and have them show up in the Logs section, you need to enable the feature:
35+
36+
```properties
37+
sentry.logs.enabled=true
38+
```
39+
2540
Minimum logging levels for `SentryAppender` can be configured in `application.properties` or `application.yml` file.
2641

2742
```properties
@@ -36,18 +51,14 @@ The default values are:
3651
- `info` or higher will send a log message to Sentry and will show up in the Logs section.
3752
- `error` or higher will send an event to Sentry and will show up in the Issues section.
3853

39-
To send logs to Sentry and have them show up in the Logs section, you need to enable the feature:
40-
41-
```properties
42-
sentry.logs.enabled=true
43-
```
44-
4554
When `SentryAppender` auto-configuration does not suit your needs, it can be turned off by setting:
4655

4756
```properties
4857
sentry.logging.enabled=false
4958
```
5059

60+
### XML Configuration
61+
5162
If you decide to opt-out from the `application.properties` based Spring Boot logging configuration, and instead configure logging in the `logback-spring.xml` file, the `SentryAppender` can be configured as follows:
5263

5364
```xml
@@ -56,7 +67,9 @@ If you decide to opt-out from the `application.properties` based Spring Boot log
5667
<include resource="org/springframework/boot/logging/logback/defaults.xml"/>
5768
<include resource="org/springframework/boot/logging/logback/console-appender.xml" />
5869

59-
<appender name="SENTRY" class="io.sentry.logback.SentryAppender" />
70+
<appender name="SENTRY" class="io.sentry.logback.SentryAppender">
71+
<minimumLevel>INFO</minimumLevel>
72+
</appender>
6073

6174
<root>
6275
<appender-ref ref="CONSOLE" />
@@ -73,63 +86,6 @@ However, if errors that may appear during startup should to be sent to Sentry, t
7386

7487
</Alert>
7588

76-
#### Mapped Diagnostic Context (MDC)
77-
78-
Starting with Sentry Java SDK version 8.24.0, you can use the <PlatformLink to="/configuration/options/#contextTags">`contextTags`</PlatformLink> option to include specific properties from the Mapped Diagnostic Context (MDC) as attributes on log entries sent to Sentry.
79-
80-
### Log4j 2
81-
82-
To use Sentry's Log4j 2 integration in Spring Boot application, you must include a dependency to the `sentry-log4j2` module:
83-
84-
```xml {tabTitle:Maven}
85-
<dependency>
86-
<groupId>io.sentry</groupId>
87-
<artifactId>sentry-log4j2</artifactId>
88-
<version>{{@inject packages.version('sentry.java.log4j2', '5.1.1') }}</version>
89-
</dependency>
90-
```
91-
92-
```groovy {tabTitle:Gradle}
93-
implementation 'io.sentry:sentry-log4j2:{{@inject packages.version('sentry.java.log4j2', '5.1.1') }}'
94-
```
95-
96-
```scala {tabTitle: SBT}
97-
libraryDependencies += "io.sentry" % "sentry-log4j2" % "{{@inject packages.version('sentry.java.log4j2', '5.1.1') }}"
98-
```
99-
100-
For other dependency managers see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-log4j2).
101-
102-
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:
103-
104-
```xml
105-
<?xml version="1.0" encoding="UTF-8"?>
106-
<Configuration>
107-
108-
<Appenders>
109-
<Console name="CONSOLE" target="SYSTEM_OUT">
110-
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
111-
</Console>
112-
<Sentry name="SENTRY"/>
113-
</Appenders>
114-
115-
<Loggers>
116-
<Root level="INFO">
117-
<AppenderRef ref="CONSOLE"/>
118-
<AppenderRef ref="SENTRY"/>
119-
</Root>
120-
</Loggers>
121-
122-
</Configuration>
123-
```
124-
125-
<Alert>
126-
127-
You do not need to configure your DSN in the Log4j 2 configuration file since Sentry is configured from the Spring Boot integration.
128-
129-
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.
130-
131-
</Alert>
132-
133-
#### Mapped Diagnostic Context (MDC)
89+
## Mapped Diagnostic Context (MDC)
13490

13591
Starting with Sentry Java SDK version 8.24.0, you can use the <PlatformLink to="/configuration/options/#contextTags">`contextTags`</PlatformLink> option to include specific properties from the Mapped Diagnostic Context (MDC) as attributes on log entries sent to Sentry.

‎platform-includes/getting-started-config/java.jul.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ dsn=___PUBLIC_DSN___
3838
# Add data like request headers and IP for users,
3939
# see https://docs.sentry.io/platforms/java/guides/jul/data-management/data-collected/ for more info
4040
send-default-pii=true
41+
<!-- ___PRODUCT_OPTION_START___ logs -->
42+
# Enable logs
43+
logs.enabled=true
44+
<!-- ___PRODUCT_OPTION_END___ logs -->
4145
```
4246
</OnboardingOption>
4347

@@ -47,6 +51,9 @@ Two log levels are used to configure this integration:
4751

4852
1. Configure the lowest level required for a log message to become an event (`minimumEventLevel`) sent to Sentry.
4953
2. Configure the lowest level a message has to be to become a breadcrumb (`minimumBreadcrumbLevel`).
54+
<OnboardingOption optionId="logs">
55+
3. Configure the lowest level a message has to be to be sent as Sentry Log (`minimumLevel`).
56+
</OnboardingOption>
5057

5158
<Alert>
5259

‎platform-includes/getting-started-config/java.log4j2.mdx‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ If the DSN is not present in the `log4j2.xml` configuration, Sentry will attempt
7171
# Add data like request headers and IP for users,
7272
# see https://docs.sentry.io/platforms/java/guides/log4j2/data-management/data-collected/ for more info
7373
send-default-pii=true
74+
// ___PRODUCT_OPTION_START___ logs
75+
logs.enabled=true
76+
// ___PRODUCT_OPTION_END___ logs
7477
```
7578
</OnboardingOption>
7679

@@ -80,6 +83,9 @@ Two log levels are used to configure this integration, as illustrated below in t
8083

8184
1. Configure the lowest level required for a log message to become an event (`minimumEventLevel`) sent to Sentry.
8285
2. Configure the lowest level a message has to be to become a breadcrumb (`minimumBreadcrumbLevel`)
86+
<OnboardingOption optionId="logs">
87+
3. Configure the lowest level a message has to be to be sent as Sentry Log (`minimumLevel`).
88+
</OnboardingOption>
8389

8490
<Alert>
8591

@@ -96,7 +102,11 @@ Breadcrumbs are kept in memory (by default the last 100 records) and are sent wi
96102
<Sentry name="SENTRY"
97103
dsn="___PUBLIC_DSN___"
98104
minimumBreadcrumbLevel="DEBUG"
99-
minimumEventLevel="WARN"/>
105+
minimumEventLevel="WARN"
106+
<!-- ___PRODUCT_OPTION_START___ logs -->
107+
minimumLevel="DEBUG"
108+
<!-- ___PRODUCT_OPTION_END___ logs -->
109+
/>
100110
```
101111
</OnboardingOption>
102112
<OnboardingOption optionId="opentelemetry">
@@ -105,6 +115,10 @@ Breadcrumbs are kept in memory (by default the last 100 records) and are sent wi
105115
<!-- Setting minimumEventLevel the default minimum level to capture an event from ERROR to WARN -->
106116
<Sentry name="SENTRY"
107117
minimumBreadcrumbLevel="DEBUG"
108-
minimumEventLevel="WARN"/>
118+
minimumEventLevel="WARN"
119+
<!-- ___PRODUCT_OPTION_START___ logs -->
120+
minimumLevel="DEBUG"
121+
<!-- ___PRODUCT_OPTION_END___ logs -->
122+
/>
109123
```
110124
</OnboardingOption>

‎platform-includes/getting-started-config/java.logback.mdx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,11 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se
2525
<dsn>___PUBLIC_DSN___</dsn>
2626
<!-- Add data like request headers and IP for users, see https://docs.sentry.io/platforms/java/guides/logback/data-management/data-collected/ for more info -->
2727
<sendDefaultPii>true</sendDefaultPii>
28+
// ___PRODUCT_OPTION_START___ logs
29+
<logs>
30+
<enabled>true</enabled>
31+
</logs>
32+
// ___PRODUCT_OPTION_END___ logs
2833
</options>
2934
</appender>
3035

@@ -87,6 +92,9 @@ Two log levels are used to configure this integration:
8792

8893
1. Configure the lowest level required for a log message to become an event (`minimumEventLevel`) sent to Sentry.
8994
2. Configure the lowest level a message has to be to become a breadcrumb (`minimumBreadcrumbLevel`).
95+
<OnboardingOption optionId="logs">
96+
3. Configure the lowest level a message has to be to be sent as Sentry Log (`minimumLevel`).
97+
</OnboardingOption>
9098

9199
<Alert>
92100

@@ -110,6 +118,10 @@ Breadcrumbs are kept in memory (by default the last 100 records) and are sent wi
110118
<minimumEventLevel>WARN</minimumEventLevel>
111119
<!-- Optionally change minimum Breadcrumbs level. Default for Breadcrumbs is INFO -->
112120
<minimumBreadcrumbLevel>DEBUG</minimumBreadcrumbLevel>
121+
// ___PRODUCT_OPTION_START___ logs
122+
<!-- Optionally change minimum Log level. Default for Logs is INFO -->
123+
<minimumLevel>DEBUG</minimumLevel>
124+
// ___PRODUCT_OPTION_END___ logs
113125
</appender>
114126
```
115127
</OnboardingOption>
@@ -121,6 +133,10 @@ Breadcrumbs are kept in memory (by default the last 100 records) and are sent wi
121133
<minimumEventLevel>WARN</minimumEventLevel>
122134
<!-- Optionally change minimum Breadcrumbs level. Default for Breadcrumbs is INFO -->
123135
<minimumBreadcrumbLevel>DEBUG</minimumBreadcrumbLevel>
136+
// ___PRODUCT_OPTION_START___ logs
137+
<!-- Optionally change minimum Log level. Default for Logs is INFO -->
138+
<minimumLevel>DEBUG</minimumLevel>
139+
// ___PRODUCT_OPTION_END___ logs
124140
</appender>
125141
```
126142
</OnboardingOption>

‎platform-includes/getting-started-config/java.mdx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,4 +60,11 @@ Sentry.init { options ->
6060
// ___PRODUCT_OPTION_END___ logs
6161
}
6262
```
63+
<OnboardingOption optionId="logs">
64+
<Alert>
65+
66+
Learn more about setting up logging in our <PlatformLink to="/logs/">Logs documentation</PlatformLink>.
67+
68+
</Alert>
69+
</OnboardingOption>
6370
</OnboardingOption>

0 commit comments

Comments
 (0)