Skip to content
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

Move the Spring Auto-Configuration doc #3900

Merged
merged 6 commits into from
Feb 1, 2024
Merged

Move the Spring Auto-Configuration doc #3900

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
de79c96
update spring boot docs
jaydeluca Jan 31, 2024
84f2b03
fix autoconfigure spelling, promote all headings, remove a few, updat…
jaydeluca Jan 31, 2024
24ccae9
Merge branch 'main' into spring-boot-doc-updates-redo
jaydeluca Jan 31, 2024
300e3de
merge main, update cspell
jaydeluca Feb 1, 2024
16cd050
remove word from cspell ignore
jaydeluca Feb 1, 2024
daedce7
Merge branch 'main' into spring-boot-doc-updates-redo
cartermp Feb 1, 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
322 changes: 295 additions & 27 deletions content/en/docs/languages/java/automatic/spring-boot.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,23 @@
---
title: Spring Boot
description: Spring Boot instrumentation for OpenTelemetry Java
cSpell:ignore: datasource logback
title: Spring Boot Starter
linkTitle: Spring Boot
jaydeluca marked this conversation as resolved.
Show resolved Hide resolved
weight: 30
description: Spring Boot instrumentation for OpenTelemetry Java
# prettier-ignore
cSpell:ignore: autoconfigurations autoconfigures Autoconfigures datasource logback springboot webflux webmvc
jaydeluca marked this conversation as resolved.
Show resolved Hide resolved
---

The [OpenTelemetry Java agent](..) with byte code instrumentation can cover most
of your needs when instrumenting
[Spring Boot](https://spring.io/projects/spring-boot) applications.

The OpenTelemetry [Spring Boot starter] can help you in the following cases:
Alternatively, the OpenTelemetry [Spring Boot starter] can help you in the
following cases:

- with Spring Boot Native image applications for which the OpenTelemetry Java
agent does not work
- the startup overhead of the OpenTelemetry Java agent exceeds your requirements
- the OpenTelemetry Java agent might not work if your application already uses
- Spring Boot Native image applications for which the OpenTelemetry Java agent
does not work
- Startup overhead of the OpenTelemetry Java agent exceeds your requirements
- OpenTelemetry Java agent might not work if your application already uses
another Java monitoring agent

[Spring Boot starter]:
Expand All @@ -28,11 +31,7 @@ instrumented using the OpenTelemetry Spring Boot starter.
The rest of this page documents the OpenTelemetry starter that works with Spring
Boot 2.0 and 3.0.

## OpenTelemetry Spring starter

### Configuration

#### Dependency management
## Dependency management

A Bill of Material
([BOM](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms))
Expand Down Expand Up @@ -69,7 +68,7 @@ With Gradle and Spring Boot, you have
[two ways](https://docs.spring.io/spring-boot/docs/current/gradle-plugin/reference/htmlsingle/)
to import a BOM.

You can use the Gradle’s native BOM support by adding dependencies:
You can use the Gradle’s native BOM support by adding `dependencies`:

```kotlin
plugins {
Expand Down Expand Up @@ -111,18 +110,15 @@ with the `io.spring.dependency-management` plugin.

{{% /alert %}}

#### OpenTelemetry Starter dependency
### OpenTelemetry Starter dependency

Add the dependency given below to enable the OpenTelemetry starter.

The OpenTelemetry starter uses OpenTelemetry Spring Boot [autoconfiguration].
The OpenTelemetry starter uses OpenTelemetry Spring Boot
[autoconfiguration](https://docs.spring.io/spring-boot/docs/current/reference/html/using.html#using.auto-configuration).
For details concerning supported libraries and features of the OpenTelemetry
autoconfiguration, see the configuration [README].

[autoconfiguration]:
https://docs.spring.io/spring-boot/docs/current/reference/html/using.html#using.auto-configuration
[README]:
https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/spring/spring-boot-autoconfigure/README.md#features
autoconfiguration, see the configuration
[README](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/spring/spring-boot-autoconfigure/README.md#features).

{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}}

Expand All @@ -145,17 +141,143 @@ dependencies {

{{% /tab %}} {{< /tabpane>}}

#### Disable data export
### Disable data export

{{% config_option name="otel.sdk.disabled" %}}

Set the value to `true` to disable data export, e.g. for testing purposes.

{{% /config_option %}}

### Additional instrumentations
## OTLP Exporter

This package provides autoconfiguration for the
[OTLP](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/otlp)
and
[Logging](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/logging)
Span Exporters.

As of 2.0.0+ the default protocol is `http/protobuf`. For more details on
exporter configuration, see
[OTLP Exporter Configuration](/docs/languages/sdk-configuration/otlp-exporter/).

### Enabling/Disabling Exporters

All exporters can be enabled or disabled as in the
[SDK autoconfiguration](https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#exporters).
This is the preferred way to enable/disable exporters and takes precedence over
the properties below.

| Feature | Property | Default Value | ConditionalOnMissingBean |
| --------------------- | ------------------------------------ | ------------- | -------------------------------------------------------- |
| OTLP Exporter | `otel.exporter.otlp.enabled` | true | - |
| OTLP Span Exporter | `otel.exporter.otlp.traces.enabled` | true | `OtlpHttpSpanExporter`, `OtlpGrpcSpanExporter` |
| OTLP Metrics Exporter | `otel.exporter.otlp.metrics.enabled` | true | `OtlpHttpMetricExporter`, `OtlpGrpcMetricExporter` |
| OTLP Logs Exporter | `otel.exporter.otlp.logs.enabled` | true | `OtlpHttpLogRecordExporter`, `OtlpGrpcLogRecordExporter` |
| Logging Exporter | `otel.exporter.logging.enabled` | false | `LoggingSpanExporter` |

#### JDBC Instrumentation
## Tracer Properties

| Feature | Property | Default Value |
| ------- | --------------------------------- | ------------- |
| Tracer | `otel.traces.sampler.probability` | 1.0 |

## Resource Properties

| Feature | Property | Default Value |
| -------- | ----------------------------------------------------------------------- | ------------- |
| Resource | `otel.springboot.resource.enabled` | true |
| | `otel.resource.attributes` (old: `otel.springboot.resource.attributes`) | empty map |

`otel.resource.attributes` supports a pattern-based resource configuration in
the application.properties like this:

```properties
otel.resource.attributes.environment=dev
otel.resource.attributes.xyz=foo
```

It's also possible to specify the resource attributes in `application.yaml`:

```yaml
otel:
resource:
attributes:
environment: dev
xyz: foo
```

Finally, the resource attributes can be specified as a comma-separated list, as
described in the
[specification](/docs/languages/sdk-configuration/general/#otel_resource_attributes):

```shell
export OTEL_RESOURCE_ATTRIBUTES="key1=value1,key2=value2"
```

The service name is determined by the following precedence rules, in accordance
with the OpenTelemetry
[specification](/docs/languages/sdk-configuration/general/#otel_service_name):

1. `otel.service.name` spring property or `OTEL_SERVICE_NAME` environment
variable (highest precedence)
2. `service.name` in `otel.resource.attributes` system/spring property or
`OTEL_RESOURCE_ATTRIBUTES` environment variable
3. `service.name` in `otel.springboot.resource.attributes` system/spring
property
4. `spring.application.name` spring property
5. The default value is `unknown_service:java` (lowest precedence)

## Automatic instrumentation

Autoconfigures OpenTelemetry instrumentation for
[spring-web](#spring-web-autoconfiguration) ,
[spring-webmvc](#spring-web-mvc-autoconfiguration), and
[spring-webflux](#spring-webflux-autoconfiguration). Leverages Spring Aspect
Oriented Programming, dependency injection, and bean post-processing to trace
spring applications.

| Feature | Property | Default Value | ConditionalOnClass |
| -------------- | --------------------------------------------- | ------------- | ---------------------- |
| spring-web | `otel.instrumentation.spring-webmvc.enabled` | true | `RestTemplate` |
| spring-webmvc | `otel.instrumentation.spring-web.enabled` | true | `OncePerRequestFilter` |
| spring-webflux | `otel.instrumentation.spring-webflux.enabled` | true | `WebClient` |

### Spring Web Autoconfiguration

Provides autoconfiguration for the `RestTemplate` trace interceptor defined in
[opentelemetry-spring-web-3.1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-web/spring-web-3.1/library).
This autoconfiguration instruments all requests sent using Spring `RestTemplate`
beans by applying a `RestTemplate` bean post processor. This feature is
supported for spring web versions 3.1+. To learn more about the OpenTelemetry
`RestTemplate` interceptor, see
[opentelemetry-spring-web-3.1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-web/spring-web-3.1/library).

### Spring Web MVC Autoconfiguration

This feature autoconfigures instrumentation for Spring WebMVC controllers by
adding a
[telemetry producing servlet `Filter`](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/spring/spring-webmvc/spring-webmvc-5.3/library/src/main/java/io/opentelemetry/instrumentation/spring/webmvc/v5_3/WebMvcTelemetryProducingFilter.java)
bean to the application context. The filter decorates the request execution with
a server span, propagating the incoming tracing context if received in the HTTP
request. To learn more about the OpenTelemetry Spring WebMVC instrumentation,
see the
[opentelemetry-spring-webmvc-5.3 instrumentation library](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-webmvc/spring-webmvc-5.3/library).

### Spring WebFlux Autoconfiguration

Provides autoconfigurations for the OpenTelemetry WebClient ExchangeFilter
defined in
[opentelemetry-spring-webflux-5.3](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-webflux/spring-webflux-5.3/library).
This autoconfiguration instruments all outgoing HTTP requests sent using
Spring's WebClient and WebClient Builder beans by applying a bean post
processor. This feature is supported for spring webflux versions 5.0+. For
details, see
[opentelemetry-spring-webflux-5.3](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-webflux/spring-webflux-5.3/library).

## Additional Instrumentations

### JDBC Instrumentation

You have two ways to enable the JDBC instrumentation with the OpenTelemetry
starter.
Expand Down Expand Up @@ -213,7 +335,7 @@ dependencies {

{{% /tab %}} {{< /tabpane>}}

#### Logging Instrumentation
### Logging Instrumentation

To enable the logging instrumentation for Logback you have to add the
OpenTelemetry appender in your `logback.xml` or `logback-spring.xml` file:
Expand Down Expand Up @@ -262,7 +384,153 @@ and
[Log4j](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/log4j/log4j-appender-2.17/library/README.md)
instrumentation libraries.

#### Other Instrumentation
### Instrumentation Annotations

This feature uses spring-aop to wrap methods annotated with `@WithSpan` in a
span. The arguments to the method can be captured as attributed on the created
span by annotating the method parameters with `@SpanAttribute`.

> **Note**: this annotation can only be applied to bean methods managed by the
> spring application context. To learn more about aspect weaving in spring, see
> [spring-aop](https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#aop).

| Feature | Property | Default Value | ConditionalOnClass |
| ----------- | ------------------------------------------ | ------------- | ------------------ |
| `@WithSpan` | `otel.instrumentation.annotations.enabled` | true | WithSpan, Aspect |

#### Dependency

{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}}

```xml
<dependencies>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-aop</artifactId>
<version>SPRING_VERSION</version>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-extension-annotations</artifactId>
<version>{{% param vers.otel %}}</version>
</dependency>
</dependencies>
```

{{% /tab %}} {{% tab header="Gradle (`gradle.build`)" lang=Gradle %}}

```kotlin
dependencies {
implementation("org.springframework:spring-aop:SPRING_VERSION")
implementation("io.opentelemetry:opentelemetry-extension-annotations:{{% param vers.otel %}}")
}
```

{{% /tab %}} {{< /tabpane>}}

#### Usage

```java
import org.springframework.stereotype.Component;

import io.opentelemetry.instrumentation.annotations.SpanAttribute;
import io.opentelemetry.instrumentation.annotations.WithSpan;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;

/**
* Test WithSpan
*/
@Component
public class TracedClass {

@WithSpan
public void tracedMethod() {
}

@WithSpan(value="span name")
public void tracedMethodWithName() {
Span currentSpan = Span.current();
currentSpan.addEvent("ADD EVENT TO tracedMethodWithName SPAN");
currentSpan.setAttribute("isTestAttribute", true);
}

@WithSpan(kind = SpanKind.CLIENT)
public void tracedClientSpan() {
}

public void tracedMethodWithAttribute(@SpanAttribute("attributeName") String parameter) {
}
}
```

### OpenTelemetry instrumentations libraries

You can configure other instrumentations with
[OpenTelemetry instrumentations libraries](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks).

## Other configurations

Instead of using the OpenTelemetry Spring starter, you can use the OpenTelemetry
autoconfiguration features with an annotation or the Zipkin starter.

### Spring support

Autoconfiguration is natively supported by Springboot applications. To enable
these features in "vanilla" use `@EnableOpenTelemetry` to complete a component
scan of this package.

```java
import io.opentelemetry.instrumentation.spring.autoconfigure.EnableOpenTelemetry;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableOpenTelemetry
public class OpenTelemetryConfig {}
```

### Zipkin starter

OpenTelemetry Zipkin Exporter Starter is a starter package that includes the
opentelemetry-api, opentelemetry-sdk, opentelemetry-extension-annotations,
opentelemetry-logging-exporter, opentelemetry-spring-boot-autoconfigurations and
spring framework starters required to setup distributed tracing. It also
provides the
[opentelemetry-exporters-zipkin](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/zipkin)
artifact and corresponding exporter autoconfiguration. Check out
[opentelemetry-spring-boot-autoconfigure](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/spring/spring-boot-autoconfigure/README.md#features)
for the list of supported libraries and features.

If an exporter is present in the classpath during runtime and a spring bean of
the exporter is missing from the spring application context, an exporter bean is
initialized and added to a simple span processor in the active tracer provider.
Check out the implementation
[here](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/OpenTelemetryAutoConfiguration.java).

{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}}

```xml
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-exporter-zipkin</artifactId>
<version>{{% param vers.otel %}}</version>
</dependency>
</dependencies>
```

{{% /tab %}} {{% tab header="Gradle (`gradle.build`)" lang=Gradle %}}

```kotlin
dependencies {
implementation("io.opentelemetry:opentelemetry-exporter-zipkin:{{% param vers.otel %}}")
}
```

{{% /tab %}} {{< /tabpane>}}

#### Configurations

| Property | Default Value | ConditionalOnClass |
| ------------------------------ | ------------- | -------------------- |
| `otel.exporter.zipkin.enabled` | true | `ZipkinSpanExporter` |
4 changes: 4 additions & 0 deletions static/refcache.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1503,6 +1503,10 @@
"StatusCode": 200,
"LastSeen": "2024-01-30T16:14:53.797365-05:00"
},
"https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#aop": {
"StatusCode": 206,
"LastSeen": "2024-01-30T20:32:51.933581-05:00"
},
"https://docs.thousandeyes.com/product-documentation/api/opentelemetry": {
"StatusCode": 206,
"LastSeen": "2024-01-30T05:18:01.115211-05:00"
Expand Down
Loading