diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index 706d44752eb0..bbfbff02af16 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -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]: @@ -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)) @@ -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 { @@ -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 %}} @@ -145,7 +141,7 @@ dependencies { {{% /tab %}} {{< /tabpane>}} -#### Disable data export +### Disable data export {{% config_option name="otel.sdk.disabled" %}} @@ -153,9 +149,135 @@ 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. @@ -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: @@ -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 + + + org.springframework + spring-aop + SPRING_VERSION + + + io.opentelemetry + opentelemetry-extension-annotations + {{% param vers.otel %}} + + +``` + +{{% /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 + + + io.opentelemetry + opentelemetry-exporter-zipkin + {{% param vers.otel %}} + + +``` + +{{% /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` | diff --git a/static/refcache.json b/static/refcache.json index fd05f9306736..ac7dfd1c1c7f 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -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"