Skip to content

Commit

Permalink
update readmes
Browse files Browse the repository at this point in the history
  • Loading branch information
lbloder committed Jan 7, 2025
1 parent c7c68dd commit 0926957
Show file tree
Hide file tree
Showing 5 changed files with 62 additions and 82 deletions.
5 changes: 4 additions & 1 deletion sentry-opentelemetry/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,11 +38,14 @@ you also need this module as a dependency.
Contains `SentrySpanProcessor` and `SentryPropagator` which are used by our Java Agent but can also
be used when manually instrumenting using OpenTelemetry. If you want to use OpenTelemetry without
the agent but still want some configuration convenience, you should rather use the
`sentry-opentelemetry-agentless` module.
`sentry-opentelemetry-agentless` module or the `sentry-opentelemetry-agentless-spring` module if you are using Spring Boot.

### `sentry-opentelemetry-agentless`
Combines all modules and dependencies needed to use Sentry with OpenTelemetry without the agent.

### `sentry-opentelemetry-agentless-spring`
Combines all modules and dependencies needed to use Sentry with OpenTelemetry in SpringBoot without an agent.

## Running without an Agent
If you want to use Sentry with OpenTelemetry without an agent, you can do so by adding the `sentry-opentelemetry-agentless` module as dependencies to your project.

Expand Down
23 changes: 14 additions & 9 deletions sentry-opentelemetry/sentry-opentelemetry-agent/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,14 @@ For more details on configuring Sentry via `sentry.properties` please see the
[docs page](https://docs.sentry.io/platforms/java/configuration/).

As an alternative to the `SENTRY_PROPERTIES_FILE` environment variable you can provide individual
settings as environment variables (e.g. `SENTRY_DSN=...`) or you may initialize `Sentry` inside
your target application:
settings as environment variables (e.g. `SENTRY_DSN=...`).

## Controlling auto initialization of Sentry

By default, if you pass either `SENTRY_DSN` or `SENTRY_PROPERTIES_FILE` as environment variable,
Sentry will automatically be initialized by this agent. To disable this behaviour, you can set
`SENTRY_AUTO_INIT=false` as environment variable. You will then have to initialize Sentry inside
the target application:

```
Sentry.init(
Expand All @@ -33,13 +39,6 @@ Sentry.init(
)
```

## Controlling auto initialization of Sentry

By default if you pass either `SENTRY_DSN` or `SENTRY_PROPERTIES_FILE` as environment variable,
Sentry will automatically be initialized by this agent. To disable this behaviour, you can set
`SENTRY_AUTO_INIT=false` as environment variable. You will then have to initialize Sentry inside
the target application.

## Debugging

To enable debug logging for Sentry, please provide `SENTRY_DEBUG=true` as environment variable or
Expand All @@ -57,6 +56,7 @@ Example log message:
```
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
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
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
```

### Traces
Expand All @@ -68,3 +68,8 @@ see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/

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

### Logs

To turn off log exporting, set `OTEL_LOGS_EXPORTER=none`
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters).
Original file line number Diff line number Diff line change
Expand Up @@ -2,53 +2,21 @@

*NOTE: Our OpenTelemetry modules are still experimental. Any feedback is welcome.*

This module allows the use of Sentry with OpenTelemetry in SpringBoot without an agent by using the OpenTelemetry Spring Boot Starter.
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/).

## How to use it

Add the latest `sentry-opentelemetry-agentless-spring` module as a dependency and add a `sentry.properties`
configuration file to your project that could look like this:
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`:

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

For more details on configuring Sentry via `sentry.properties` please see the
[docs page](https://docs.sentry.io/platforms/java/configuration/).

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

```
Sentry.init(
options -> {
options.setDsn("...");
...
OpenTelemetryUtil.applyOpenTelemetryOptions(options, false);
}
)
```

## Getting rid of exporter error messages

In case you are using this module without needing to use any OpenTelemetry exporters you can add
the following environment variables to turn off exporters and stop seeing error messages about
servers not being reachable in the logs.

Example log message:
```
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
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
```

### Traces

To turn off exporting of traces you can set `OTEL_TRACES_EXPORTER=none`
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters)

### Metrics
This module will automatically configure OpenTelemetry and Sentry for you.

To turn off exporting of metrics you can set `OTEL_METRICS_EXPORTER=none`
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters)
With the dependency and configuration in place, just run your SpringBoot application as usual.
60 changes: 32 additions & 28 deletions sentry-opentelemetry/sentry-opentelemetry-agentless/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,38 +17,42 @@ For more details on configuring Sentry via `sentry.properties` please see the
[docs page](https://docs.sentry.io/platforms/java/configuration/).

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

Run your application with the following JVM arguments:
```
Sentry.init(
options -> {
options.setDsn("...");
...
OpenTelemetryUtil.applyOpenTelemetryOptions(options, false);
}
)
-Dotel.java.global-autoconfigure.enabled=true
```

## Getting rid of exporter error messages

In case you are using this module without needing to use any OpenTelemetry exporters you can add
the following environment variables to turn off exporters and stop seeing error messages about
servers not being reachable in the logs.

Example log message:
```
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
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
You may also want to set the following environment variables to if you do not use OTEL exporters:
`OTEL_LOGS_EXPORTER=none;OTEL_METRICS_EXPORTER=none;OTEL_TRACES_EXPORTER=none`

Alternatively you can initialize OpenTelemetry programmatically like this:

```java
// Initialize OpenTelemetry by using the AutoConfiguredOpenTelemetrySdk which automatically
// registers the `SentrySpanProcessor` and `SentryPropagator` and others.
// Also, you need to disable the OTEL exporters if you do not use them.
AutoConfiguredOpenTelemetrySdk.builder()
.setResultAsGlobal()
.addPropertiesSupplier(() -> {
final Map<String, String> properties = new HashMap<>();
properties.put("otel.logs.exporter", "none");
properties.put("otel.metrics.exporter", "none");
properties.put("otel.traces.exporter", "none");
return properties;
})
.build();
```

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

To turn off exporting of traces you can set `OTEL_TRACES_EXPORTER=none`
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters)

### Metrics

To turn off exporting of metrics you can set `OTEL_METRICS_EXPORTER=none`
see [OpenTelemetry GitHub](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure#otlp-exporter-span-metric-and-log-exporters)
```java
// Initialize Sentry
Sentry.init(
options -> {
options.setDsn("...");
...
}
)
```
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Sentry Sample Spring Boot 3.0+

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/).
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.

## How to run?

Expand Down

0 comments on commit 0926957

Please sign in to comment.