Skip to content

Commit f5a6ec4

Browse files
lbloderadinauer
authored and
lcian
committed
update otel readme files (#3978)
* update readmes for noagent samples, add otel properties to application.properties in noagent samples * update readme for console - noagent * update opentelemetry and optentelemetry agent readme * add java options and new agentless module to readme * update readmes * Update sentry-opentelemetry/README.md Co-authored-by: Alexander Dinauer <adinauer@users.noreply.github.com> * Update sentry-opentelemetry/README.md Co-authored-by: Alexander Dinauer <adinauer@users.noreply.github.com> * Update sentry-opentelemetry/sentry-opentelemetry-agent/README.md Co-authored-by: Alexander Dinauer <adinauer@users.noreply.github.com> * Update sentry-opentelemetry/sentry-opentelemetry-agentless/README.md Co-authored-by: Alexander Dinauer <adinauer@users.noreply.github.com> * Update sentry-opentelemetry/README.md Co-authored-by: Alexander Dinauer <adinauer@users.noreply.github.com> * remove experimental note in opentelemetry readmes --------- Co-authored-by: Alexander Dinauer <adinauer@users.noreply.github.com>
1 parent 3109e49 commit f5a6ec4

File tree

9 files changed

+117
-98
lines changed

9 files changed

+117
-98
lines changed

‎sentry-opentelemetry/README.md‎

Lines changed: 48 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# sentry-opentelemetry
22

3-
*NOTE: Our OpenTelemetry modules are still experimental. Any feedback is welcome.*
4-
53
## OpenTelemetry
64

75
More information on OpenTelemetry can be found on their [website](https://opentelemetry.io/) as well
@@ -21,8 +19,7 @@ application. Please see the module [README](sentry-opentelemetry-agent/README.md
2119

2220
This contains customizations to the OpenTelemetry Java Agent such as registering the
2321
`SentrySpanProcessor` and `SentryPropagator` as well as providing default properties that
24-
enable the `sentry` propagator and disable exporters so our agent doesn't trigger lots of log
25-
warnings due to OTLP server not being there. This can also be used without the agent.
22+
enable the `sentry` propagator.
2623

2724
### `sentry-opentelemetry-bootstrap`
2825

@@ -39,4 +36,50 @@ you also need this module as a dependency.
3936
Contains `SentrySpanProcessor` and `SentryPropagator` which are used by our Java Agent but can also
4037
be used when manually instrumenting using OpenTelemetry. If you want to use OpenTelemetry without
4138
the agent but still want some configuration convenience, you should rather use the
42-
`sentry-opentelemetry-agentcustomization` module.
39+
`sentry-opentelemetry-agentless` module or the `sentry-opentelemetry-agentless-spring` module if you are using Spring Boot.
40+
41+
### `sentry-opentelemetry-agentless`
42+
Combines all modules and dependencies needed to use Sentry with OpenTelemetry without the agent.
43+
44+
### `sentry-opentelemetry-agentless-spring`
45+
Combines all modules and dependencies needed to use Sentry with OpenTelemetry in Spring Boot without an agent.
46+
47+
## Running without an Agent
48+
If you want to use Sentry with OpenTelemetry without an agent, you can do so by adding the `sentry-opentelemetry-agentless` (or `sentry-opentelemetry-agentless-spring`) module as dependency to your project.
49+
50+
And run your application with the following JVM arguments:
51+
```
52+
-Dotel.java.global-autoconfigure.enabled=true
53+
```
54+
You may also want to set the following environment variables to if you do not use OpenTelemetry exporters:
55+
`OTEL_LOGS_EXPORTER=none;OTEL_METRICS_EXPORTER=none;OTEL_TRACES_EXPORTER=none`
56+
57+
Alternatively you can initialize OpenTelemetry programmatically like this:
58+
59+
```java
60+
// Initialize OpenTelemetry by using the AutoConfiguredOpenTelemetrySdk which automatically
61+
// registers the `SentrySpanProcessor` and `SentryPropagator` and others.
62+
// Also, you need to disable the OTEL exporters if you do not use them.
63+
AutoConfiguredOpenTelemetrySdk.builder()
64+
.setResultAsGlobal()
65+
.addPropertiesSupplier(() -> {
66+
final Map<String, String> properties = new HashMap<>();
67+
properties.put("otel.logs.exporter", "none");
68+
properties.put("otel.metrics.exporter", "none");
69+
properties.put("otel.traces.exporter", "none");
70+
return properties;
71+
})
72+
.build();
73+
```
74+
75+
And then initialize Sentry as usual:
76+
77+
```java
78+
// Initialize Sentry
79+
Sentry.init(
80+
options -> {
81+
options.setDsn("...");
82+
...
83+
}
84+
)
85+
```

‎sentry-opentelemetry/sentry-opentelemetry-agent/README.md‎

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# sentry-opentelemetry-agent
22

3-
*NOTE: Our OpenTelemetry modules are still experimental. Any feedback is welcome.*
4-
53
## How to use it
64

75
Download the latest `sentry-opentelemetry-agent.jar` and use it when launching your Java
@@ -21,30 +19,24 @@ For more details on configuring Sentry via `sentry.properties` please see the
2119
[docs page](https://docs.sentry.io/platforms/java/configuration/).
2220

2321
As an alternative to the `SENTRY_PROPERTIES_FILE` environment variable you can provide individual
24-
settings as environment variables (e.g. `SENTRY_DSN=...`) or you may initialize `Sentry` inside
25-
your target application. If you do so, please make sure to set the `instrumenter` to `otel`, e.g.
26-
like this:
22+
settings as environment variables (e.g. `SENTRY_DSN=...`).
23+
24+
## Controlling auto initialization of Sentry
25+
26+
By default, if you pass either `SENTRY_DSN` or `SENTRY_PROPERTIES_FILE` as environment variable,
27+
Sentry will automatically be initialized by this agent. To disable this behaviour, you can set
28+
`SENTRY_AUTO_INIT=false` as environment variable. You will then have to use a Sentry SDK that takes care of initialization or initialize Sentry manually inside
29+
the target application:
2730

2831
```
2932
Sentry.init(
3033
options -> {
3134
options.setDsn("...");
3235
...
33-
options.setInstrumenter(Instrumenter.OTEL);
3436
}
3537
)
3638
```
3739

38-
Using the `otel` instrumenter will ensure `Sentry` instrumentation will be done via OpenTelemetry
39-
and integrations as well as direct interactions with transactions and spans have no effect.
40-
41-
## Controlling auto initialization of Sentry
42-
43-
By default if you pass either `SENTRY_DSN` or `SENTRY_PROPERTIES_FILE` as environment variable,
44-
Sentry will automatically be initialized by this agent. To disable this behaviour, you can set
45-
`SENTRY_AUTO_INIT=false` as environment variable. You will then have to initialize Sentry inside
46-
the target application.
47-
4840
## Debugging
4941

5042
To enable debug logging for Sentry, please provide `SENTRY_DEBUG=true` as environment variable or
@@ -62,6 +54,7 @@ Example log message:
6254
```
6355
ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export spans. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4317
6456
ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export metrics. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4317
57+
ERROR io.opentelemetry.exporter.internal.http.HttpExporter - Failed to export logs. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4318
6558
```
6659

6760
### Traces
@@ -73,3 +66,8 @@ see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/
7366

7467
To turn off exporting of metrics you can set `OTEL_METRICS_EXPORTER=none`
7568
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters)
69+
70+
### Logs
71+
72+
To turn off log exporting, set `OTEL_LOGS_EXPORTER=none`
73+
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters).

‎sentry-opentelemetry/sentry-opentelemetry-agentless-spring/README.md‎

Lines changed: 10 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,20 @@
11
# sentry-opentelemetry-agentless-spring
22

3-
*NOTE: Our OpenTelemetry modules are still experimental. Any feedback is welcome.*
3+
This module allows the use of Sentry with OpenTelemetry in SpringBoot without an agent by using the OpenTelemetry Spring Boot Starter.
4+
For guidance on when to use this module instead of the agent, please have a look at the [OpenTelemetry Spring Boot Starter documentation](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/).
45

56
## How to use it
67

7-
Add the latest `sentry-opentelemetry-agentless-spring` module as a dependency and add a `sentry.properties`
8-
configuration file to your project that could look like this:
8+
Add the latest `sentry-opentelemetry-agentless-spring` module as a dependency to your Sentry enabled [SpringBoot](https://docs.sentry.io/platforms/java/guides/spring-boot/) application and add the following to your `application.properties`:
99

1010
```properties
11-
# NOTE: Replace the test DSN below with YOUR OWN DSN to see the events from this app in your Sentry project/dashboard
12-
dsn=https://502f25099c204a2fbf4cb16edc5975d1@o447951.ingest.sentry.io/5428563
13-
traces-sample-rate=1.0
11+
# OTEL configuration
12+
otel.propagators=tracecontext,baggage,sentry
13+
otel.logs.exporter=none
14+
otel.metrics.exporter=none
15+
otel.traces.exporter=none
1416
```
1517

16-
For more details on configuring Sentry via `sentry.properties` please see the
17-
[docs page](https://docs.sentry.io/platforms/java/configuration/).
18+
This module will automatically configure OpenTelemetry and Sentry for you.
1819

19-
As an alternative to the `SENTRY_PROPERTIES_FILE` environment variable you can provide individual
20-
settings as environment variables (e.g. `SENTRY_DSN=...`) or you may initialize `Sentry` inside
21-
your target application. If you do so, please make sure to apply OpenTelemetry specific options, e.g.
22-
like this:
23-
24-
```
25-
Sentry.init(
26-
options -> {
27-
options.setDsn("...");
28-
...
29-
OpenTelemetryUtil.applyOpenTelemetryOptions(options, false);
30-
}
31-
)
32-
```
33-
34-
## Getting rid of exporter error messages
35-
36-
In case you are using this module without needing to use any OpenTelemetry exporters you can add
37-
the following environment variables to turn off exporters and stop seeing error messages about
38-
servers not being reachable in the logs.
39-
40-
Example log message:
41-
```
42-
ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export spans. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4317
43-
ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export metrics. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4317
44-
```
45-
46-
### Traces
47-
48-
To turn off exporting of traces you can set `OTEL_TRACES_EXPORTER=none`
49-
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters)
50-
51-
### Metrics
52-
53-
To turn off exporting of metrics you can set `OTEL_METRICS_EXPORTER=none`
54-
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters)
20+
With the dependency and configuration in place, just run your SpringBoot application as usual.

‎sentry-opentelemetry/sentry-opentelemetry-agentless/README.md‎

Lines changed: 32 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# sentry-opentelemetry-agentless
22

3-
*NOTE: Our OpenTelemetry modules are still experimental. Any feedback is welcome.*
4-
53
## How to use it
64

75
Add the latest `sentry-opentelemetry-agentless` module as a dependency and add a `sentry.properties`
@@ -17,38 +15,42 @@ For more details on configuring Sentry via `sentry.properties` please see the
1715
[docs page](https://docs.sentry.io/platforms/java/configuration/).
1816

1917
As an alternative to the `SENTRY_PROPERTIES_FILE` environment variable you can provide individual
20-
settings as environment variables (e.g. `SENTRY_DSN=...`) or you may initialize `Sentry` inside
21-
your target application. If you do so, please make sure to apply OpenTelemetry specific options, e.g.
22-
like this:
18+
settings as environment variables (e.g. `SENTRY_DSN=...`).
2319

20+
Run your application with the following JVM arguments:
2421
```
25-
Sentry.init(
26-
options -> {
27-
options.setDsn("...");
28-
...
29-
OpenTelemetryUtil.applyOpenTelemetryOptions(options, false);
30-
}
31-
)
22+
-Dotel.java.global-autoconfigure.enabled=true
3223
```
3324

34-
## Getting rid of exporter error messages
35-
36-
In case you are using this module without needing to use any OpenTelemetry exporters you can add
37-
the following environment variables to turn off exporters and stop seeing error messages about
38-
servers not being reachable in the logs.
39-
40-
Example log message:
41-
```
42-
ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export spans. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4317
43-
ERROR io.opentelemetry.exporter.internal.grpc.OkHttpGrpcExporter - Failed to export metrics. The request could not be executed. Full error message: Failed to connect to localhost/[0:0:0:0:0:0:0:1]:4317
25+
You may also want to set the following environment variables to if you do not use OpenTelemetry exporters:
26+
`OTEL_LOGS_EXPORTER=none;OTEL_METRICS_EXPORTER=none;OTEL_TRACES_EXPORTER=none`
27+
28+
Alternatively you can initialize OpenTelemetry programmatically like this:
29+
30+
```java
31+
// Initialize OpenTelemetry by using the AutoConfiguredOpenTelemetrySdk which automatically
32+
// registers the `SentrySpanProcessor` and `SentryPropagator` and others.
33+
// Also, you need to disable the OTEL exporters if you do not use them.
34+
AutoConfiguredOpenTelemetrySdk.builder()
35+
.setResultAsGlobal()
36+
.addPropertiesSupplier(() -> {
37+
final Map<String, String> properties = new HashMap<>();
38+
properties.put("otel.logs.exporter", "none");
39+
properties.put("otel.metrics.exporter", "none");
40+
properties.put("otel.traces.exporter", "none");
41+
return properties;
42+
})
43+
.build();
4444
```
4545

46-
### Traces
46+
If you're not using `sentry.properties` or environment variables you can then initialize Sentry programmatically as usual:
4747

48-
To turn off exporting of traces you can set `OTEL_TRACES_EXPORTER=none`
49-
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters)
50-
51-
### Metrics
52-
53-
To turn off exporting of metrics you can set `OTEL_METRICS_EXPORTER=none`
54-
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters)
48+
```java
49+
// Initialize Sentry
50+
Sentry.init(
51+
options -> {
52+
options.setDsn("...");
53+
...
54+
}
55+
)
56+
```

‎sentry-samples/sentry-samples-console-opentelemetry-noagent/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Sentry Sample Console
22

3-
Sample application showing how to use Sentry manually without any framework integration.
3+
Sample application showing how to use Sentry with OpenTelemetry manually without any framework integration and without java agent.
44

55
## How to run?
66

‎sentry-samples/sentry-samples-spring-boot-jakarta-opentelemetry-noagent/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Sentry Sample Spring Boot 3.0+
22

3-
Sample application showing how to use Sentry with [Spring boot](http://spring.io/projects/spring-boot) from version `3.0` onwards.
3+
Sample application showing how to use Sentry with [Spring boot](http://spring.io/projects/spring-boot) from version `3.0` onwards integrated with the [OpenTelemetry Spring Boot Starter](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/) without an agent.
44

55
## How to run?
66

‎sentry-samples/sentry-samples-spring-boot-jakarta-opentelemetry-noagent/src/main/resources/application.properties‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,4 +31,8 @@ spring.graphql.graphiql.enabled=true
3131
spring.graphql.websocket.path=/graphql
3232
spring.quartz.job-store-type=memory
3333

34+
# OTEL configuration
3435
otel.propagators=tracecontext,baggage,sentry
36+
otel.logs.exporter=none
37+
otel.metrics.exporter=none
38+
otel.traces.exporter=none

‎sentry-samples/sentry-samples-spring-boot-opentelemetry-noagent/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Sentry Sample Spring Boot
22

3-
Sample application showing how to use Sentry with [Spring boot](http://spring.io/projects/spring-boot).
3+
Sample application showing how to use Sentry with [Spring boot](http://spring.io/projects/spring-boot) integrated with the [OpenTelemetry Spring Boot Starter](https://opentelemetry.io/docs/zero-code/java/spring-boot-starter/).
44

55
## How to run?
66

‎sentry-samples/sentry-samples-spring-boot-opentelemetry-noagent/src/main/resources/application.properties‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,9 @@ spring.datasource.username=sa
2323
spring.datasource.password=
2424
spring.graphql.graphiql.enabled=true
2525
spring.graphql.websocket.path=/graphql
26+
27+
# OTEL configuration
28+
otel.propagators=tracecontext,baggage,sentry
29+
otel.logs.exporter=none
30+
otel.metrics.exporter=none
31+
otel.traces.exporter=none

0 commit comments

Comments
 (0)