Skip to content

Commit

Permalink
Move the Spring Auto-Configuration doc (#3900)
Browse files Browse the repository at this point in the history 
Co-authored-by: Phillip Carter <[email protected]>
  • Loading branch information
@jaydeluca @cartermp
jaydeluca and cartermp authored Feb 1, 2024
1 parent c310449 commit 12b42d4
Show file tree
Hide file tree
Showing 2 changed files with 299 additions and 27 deletions.
322 changes: 295 additions & 27 deletions content/en/docs/languages/java/automatic/spring-boot.md
View file
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
weight: 30
description: Spring Boot instrumentation for OpenTelemetry Java
# prettier-ignore
cSpell:ignore: autoconfigurations autoconfigures datasource logback springboot webflux webmvc
---

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
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

0 comments on commit 12b42d4

Please sign in to comment.