Skip to content

Commit 88b1100

Browse files
adinaueradinauer
authored
Update platform docs for v8 and use OpenTelemetry (#12232)
* Update OTel docs for Java v8 * Change platform docs for v8 and use OTel * move includes to index file * CR changes
1 parent bf52a2c commit 88b1100

File tree

21 files changed

+188
-41
lines changed

21 files changed

+188
-41
lines changed

‎docs/platforms/java/common/index.mdx‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,14 @@ Sentry captures data by using an SDK within your application’s runtime.
1212

1313
<PlatformContent includePath="getting-started-install" />
1414

15-
## Configure
15+
<PlatformContent includePath="getting-started-install/opentelemetry" />
1616

17-
Configuration should happen as early as possible in your application's lifecycle.
17+
## Configure
1818

1919
<PlatformContent includePath="getting-started-config" />
2020

21+
<PlatformContent includePath="getting-started-config/opentelemetry" />
22+
2123
## Verify
2224

2325
This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
Configuration should happen as early as possible in your application's lifecycle.
2+
13
The following example configures a `ConsoleHandler` that logs to standard out at the `INFO` level and a `SentryHandler` that logs to the Sentry server at the `WARN` level. The `ConsoleHandler` is only provided as an example of a non-Sentry appender that is set to a different logging threshold, like one you may already have in your project.
24

35
<Note>
@@ -25,6 +27,7 @@ When starting your application, add the `java.util.logging.config.file` to the s
2527
java -Djava.util.logging.config.file=/path/to/app.properties MyClass
2628
```
2729

30+
<OnboardingOption optionId="opentelemetry" hideForThisOption>
2831
### DSN Configuration
2932

3033
Sentry reads the DSN 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.
@@ -33,6 +36,7 @@ Sentry reads the DSN from the system property `sentry.dsn`, environment variable
3336
```properties {tabTitle:sentry.properties}
3437
dsn=___PUBLIC_DSN___
3538
```
39+
</OnboardingOption>
3640

3741
### Minimum Log Level
3842

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

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
Configuration should happen as early as possible in your application's lifecycle.
2+
13
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.
24

35
<Note>
@@ -6,6 +8,7 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se
68

79
</Note>
810

11+
<OnboardingOption optionId="opentelemetry" hideForThisOption>
912
```xml
1013
<?xml version="1.0" encoding="UTF-8"?>
1114
<Configuration>
@@ -26,9 +29,34 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se
2629

2730
</Configuration>
2831
```
32+
</OnboardingOption>
33+
34+
<OnboardingOption optionId="opentelemetry">
35+
```xml
36+
<?xml version="1.0" encoding="UTF-8"?>
37+
<Configuration>
38+
39+
<Appenders>
40+
<Console name="CONSOLE" target="SYSTEM_OUT">
41+
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
42+
</Console>
43+
<Sentry name="SENTRY"/>
44+
</Appenders>
45+
46+
<Loggers>
47+
<Root level="INFO">
48+
<AppenderRef ref="CONSOLE"/>
49+
<AppenderRef ref="SENTRY" level="ERROR"/>
50+
</Root>
51+
</Loggers>
52+
53+
</Configuration>
54+
```
55+
</OnboardingOption>
2956

3057
`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.
3158

59+
<OnboardingOption optionId="opentelemetry" hideForThisOption>
3260
### DSN Configuration
3361

3462
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.
@@ -38,6 +66,7 @@ Note that **you need to configure your DSN** (client key) only if you wish to in
3866
```
3967

4068
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.
69+
</OnboardingOption>
4170

4271
### Minimum Log Level
4372

@@ -54,7 +83,7 @@ Setting `minimumEventLevel` or `minimumBreadcrumbLevel` in `log4j2.xml` only aff
5483

5584
Breadcrumbs are kept in memory (by default the last 100 records) and are sent with events. For example, by default, if you log 100 entries with `logger.info` or `logger.warn`, no event is sent to Sentry. If you then log with `logger.error`, an event is sent to Sentry that includes those 100 `info` or `warn` messages. For this to work, `SentryAppender` needs to receive **all** log entries to decide what to keep as breadcrumb or send as event. Set the `SentryAppender` log level configuration to a value lower than what is set for the `minimumBreadcrumbLevel` and `minimumEventLevel` so that `SentryAppender` receives these log messages.
5685

57-
86+
<OnboardingOption optionId="opentelemetry" hideForThisOption>
5887
```xml
5988
<!-- Setting minimumBreadcrumbLevel modifies the default minimum level to add breadcrumbs from INFO to DEBUG -->
6089
<!-- Setting minimumEventLevel the default minimum level to capture an event from ERROR to WARN -->
@@ -63,3 +92,13 @@ Breadcrumbs are kept in memory (by default the last 100 records) and are sent wi
6392
minimumBreadcrumbLevel="DEBUG"
6493
minimumEventLevel="WARN"/>
6594
```
95+
</OnboardingOption>
96+
<OnboardingOption optionId="opentelemetry">
97+
```xml
98+
<!-- Setting minimumBreadcrumbLevel modifies the default minimum level to add breadcrumbs from INFO to DEBUG -->
99+
<!-- Setting minimumEventLevel the default minimum level to capture an event from ERROR to WARN -->
100+
<Sentry name="SENTRY"
101+
minimumBreadcrumbLevel="DEBUG"
102+
minimumEventLevel="WARN"/>
103+
```
104+
</OnboardingOption>

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

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
Configuration should happen as early as possible in your application's lifecycle.
2+
13
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 `ERROR` level.
24

35
<Note>
@@ -6,7 +8,7 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se
68

79
</Note>
810

9-
11+
<OnboardingOption optionId="opentelemetry" hideForThisOption>
1012
```xml
1113
<configuration>
1214
<!-- Configure the Console appender -->
@@ -32,7 +34,32 @@ The `ConsoleAppender` is provided only as an example of a non-Sentry appender se
3234
</root>
3335
</configuration>
3436
```
37+
</OnboardingOption>
38+
39+
<OnboardingOption optionId="opentelemetry">
40+
```xml
41+
<configuration>
42+
<!-- Configure the Console appender -->
43+
<appender name="Console" class="ch.qos.logback.core.ConsoleAppender">
44+
<encoder>
45+
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
46+
</encoder>
47+
</appender>
48+
49+
<!-- Configure the Sentry appender, overriding the logging threshold to the WARN level -->
50+
<appender name="Sentry" class="io.sentry.logback.SentryAppender"></appender>
3551

52+
<!-- Enable the Console and Sentry appenders, Console is provided as an example
53+
of a non-Sentry logger that is set to a different logging threshold -->
54+
<root level="INFO">
55+
<appender-ref ref="Console" />
56+
<appender-ref ref="Sentry" />
57+
</root>
58+
</configuration>
59+
```
60+
</OnboardingOption>
61+
62+
<OnboardingOption optionId="opentelemetry" hideForThisOption>
3663
### DSN Configuration
3764

3865
Note that **you need to configure your DSN** (client key).
@@ -48,6 +75,7 @@ Note that **you need to configure your DSN** (client key).
4875
```
4976

5077
If the DSN is not present in the `logback.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.
78+
</OnboardingOption>
5179

5280
### Minimum Log Level
5381

@@ -65,6 +93,7 @@ Setting `minimumEventLevel` or `minimumBreadcrumbLevel` in `logback.xml` only af
6593
Breadcrumbs are kept in memory (by default the last 100 records) and are sent with events. For example, by default, if you log 100 entries with `logger.info` or `logger.warn`, no event is sent to Sentry. If you then log with `logger.error`, an event is sent to Sentry which includes those 100 `info` or `warn` messages. For this to work, `SentryAppender` needs to receive **all** log entries to decide what to keep as breadcrumb or sent as event. Set the `SentryAppender` log level configuration to a value lower than what is set for the `minimumBreadcrumbLevel` and `minimumEventLevel` so that `SentryAppender` receives these log messages.
6694

6795

96+
<OnboardingOption optionId="opentelemetry" hideForThisOption>
6897
```xml
6998
<appender name="Sentry" class="io.sentry.logback.SentryAppender">
7099
<options>
@@ -77,3 +106,15 @@ Breadcrumbs are kept in memory (by default the last 100 records) and are sent wi
77106
<minimumBreadcrumbLevel>DEBUG</minimumBreadcrumbLevel>
78107
</appender>
79108
```
109+
</OnboardingOption>
110+
111+
<OnboardingOption optionId="opentelemetry">
112+
```xml
113+
<appender name="Sentry" class="io.sentry.logback.SentryAppender">
114+
<!-- Optionally change minimum Event level. Default for Events is ERROR -->
115+
<minimumEventLevel>WARN</minimumEventLevel>
116+
<!-- Optionally change minimum Breadcrumbs level. Default for Breadcrumbs is INFO -->
117+
<minimumBreadcrumbLevel>DEBUG</minimumBreadcrumbLevel>
118+
</appender>
119+
```
120+
</OnboardingOption>

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
<OnboardingOption optionId="opentelemetry" hideForThisOption>
2+
Configuration should happen as early as possible in your application's lifecycle.
3+
14
```java {tabTitle: Java} {"onboardingOptions": {"performance": "5-9"}}
25
import io.sentry.Sentry;
36

@@ -23,3 +26,4 @@ Sentry.init { options ->
2326
options.tracesSampleRate = 1.0
2427
}
2528
```
29+
</OnboardingOption>

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

Lines changed: 4 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
<OnboardingOption optionId="opentelemetry" hideForThisOption>
2+
Configuration should happen as early as possible in your application's lifecycle.
3+
14
The following example configures a `SentryInitializer` servlet container initializer that initializes Sentry on application startup.
25

36

@@ -39,23 +42,7 @@ class SentryInitializer : ServletContainerInitializer {
3942

4043
Create a file in `src/main/resources/META-INF/services` named `javax.servlet.ServletContainerInitializer`, with a full name of your custom `SentryInitializer` class as a content:
4144

42-
4345
```properties
4446
sentry.sample.SentryInitializer
4547
```
46-
47-
```java {tabTitle: Java}
48-
import io.sentry.Sentry;
49-
50-
Sentry.init(options -> {
51-
options.setDsn("___PUBLIC_DSN___");
52-
});
53-
```
54-
55-
```kotlin {tabTitle: Kotlin}
56-
import io.sentry.Sentry
57-
58-
Sentry.init { options ->
59-
options.dsn = "___PUBLIC_DSN___"
60-
}
61-
```
48+
</OnboardingOption>

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
Configuration should happen as early as possible in your application's lifecycle.
2+
13
The `sentry-spring` and `sentry-spring-jakarta` libraries provide an `@EnableSentry` annotation that registers all required Spring beans. `@EnableSentry` can be placed on any class annotated with [@Configuration](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html) including the main entry class in Spring Boot applications annotated with [@SpringBootApplication](https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/SpringBootApplication.html).
24

35

@@ -95,3 +97,12 @@ import org.springframework.core.Ordered
9597
)
9698
class SentryConfiguration
9799
```
100+
101+
<OnboardingOption optionId="performance">
102+
103+
The SDK can be configured using a `sentry.properties` file:
104+
105+
```properties {filename:sentry.properties}
106+
traces-sample-rate=1.0
107+
```
108+
</OnboardingOption>

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<OnboardingOption optionId="opentelemetry">
2+
3+
The SDK can be configured using a `sentry.properties` file:
4+
5+
```properties {filename:sentry.properties} {"onboardingOptions": {"performance": "2-2"}}
6+
dsn=___PUBLIC_DSN___
7+
traces-sample-rate=1.0
8+
```
9+
</OnboardingOption>

‎platform-includes/getting-started-config/opentelemetry/java.spring-boot.mdx‎

Whitespace-only changes.

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

Whitespace-only changes.

0 commit comments

Comments
 (0)