From de79c96c7f08b5d93af91a6cbf046806708e2314 Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Tue, 30 Jan 2024 20:34:30 -0500 Subject: [PATCH] update spring boot docs --- .../languages/java/automatic/spring-boot.md | 298 +++++++++++++++++- static/refcache.json | 4 + 2 files changed, 290 insertions(+), 12 deletions(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index 06b4a8980224..10ad1069a9bb 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -3,19 +3,21 @@ title: Spring Boot linkTitle: Spring Boot weight: 30 description: Spring Boot instrumentation for OpenTelemetry Java -cSpell:ignore: autoconfigure datasource logback springboot springframework +# prettier-ignore +cSpell:ignore: autoconfiguration autoconfigurations autoconfigure autoconfigures classpath datasource logback springboot springframework 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]: @@ -31,9 +33,7 @@ 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)) @@ -70,7 +70,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 { @@ -154,7 +154,134 @@ Set the value to `true` to disable data export, e.g. for testing purposes. {{% /config_option %}} -### Additional instrumentations +### OTLP Exporter + +This package provides auto configuration 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 auto-configuration](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` | + +### 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 + +Auto-configures OpenTelemetry instrumentation for +[spring-web](#spring-web-auto-configuration) , +[spring-webmvc](#spring-web-mvc-auto-configuration), and +[spring-webflux](#spring-webflux-auto-configuration). 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 Auto Configuration + +Provides autoconfiguration for the OpenTelemetry 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). +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+. Check out +[opentelemetry-spring-web-3.1](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-web/spring-web-3.1) +to learn more about the OpenTelemetry RestTemplateInterceptor. + +#### Spring Web MVC Auto Configuration + +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. This filter decorates the request execution +with an OpenTelemetry server span, propagating the incoming tracing context if +received in the HTTP request. Check out +[`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) +to learn more about the OpenTelemetry Spring WebMVC instrumentation. + +#### Spring WebFlux Auto Configuration + +Provides auto-configurations 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). +This auto-configuration 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+. Check out +[opentelemetry-spring-webflux-5.3](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/spring/spring-webflux/spring-webflux-5.3) +to learn more about the OpenTelemetry WebClientFilter. + +### Additional Instrumentations #### JDBC Instrumentation @@ -263,7 +390,154 @@ 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. Check out +[spring-aop](https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#aop) +to learn more about aspect weaving in spring. + +| 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 + +Auto-configuration 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 auto-configuration. 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 d5beeea1048a..bb7e34f26601 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -1455,6 +1455,10 @@ "StatusCode": 200, "LastSeen": "2023-11-14T09:30:42.69906-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"