From 78cbec6121f391d6da803f2a8018a9784eb26810 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Fri, 15 Mar 2024 14:19:18 +0100 Subject: [PATCH 01/10] spring starter can now use all sdk autoconfig properties --- .../languages/java/automatic/spring-boot.md | 63 +++++++++++-------- 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index e7f05868295b..8ac3c1cadb52 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -164,6 +164,13 @@ This spring starter supports which means that you can see and autocomplete all available properties in your IDE. +The OpenTelemetry Starter supports all properties from the +[Configuration](/docs/languages/java/automatic/configuration/) page (since +2.2.0). + +The only difference is that the OpenTelemetry Spring Boot starter uses +`http/protobuf` as the default protocol for the OTLP exporter (since 2.0.0). + #### Disable the OpenTelemetry Starter {{% config_option name="otel.sdk.disabled" %}} @@ -172,57 +179,59 @@ Set the value to `true` to disable the starter, e.g. for testing purposes. {{% /config_option %}} -#### OpenTelemetry Data Exporters +#### Spring Boot properties integration -This package provides autoconfiguration the following exporters: +All OpenTelemetry properties can be set in the `application.properties` or the +`application.yaml` file. -- OTLP -- Logging +Lists and maps can use both the OpenTelemetry and Spring Boot flavors. -All available properties are listed in the -[Configuration](/docs/languages/java/automatic/configuration/) page. +##### OpenTelemetry properties style -The only difference is that the OpenTelemetry Spring Boot starter uses -`http/protobuf` as the default protocol for the OTLP exporter (as of 2.0.0+). +The OpenTelemetry Starter supports the OpenTelemetry properties as described in +the +[specification](/docs/languages/sdk-configuration/general/#otel_resource_attributes): -#### Tracer Properties +`application.properties`: -| Feature | Property | Default Value | -| ------- | --------------------------------- | ------------- | -| Tracer | `otel.traces.sampler.probability` | 1.0 | +```properties +otel.propagators=tracecontext,b3 +otel.resource.attributes=environment=dev,xyz=foo +``` -#### Resource Properties +This style is convenient to use in environment variables: -| Feature | Property | Default Value | -| -------- | ---------------------------------- | ------------- | -| Resource | `otel.springboot.resource.enabled` | true | -| | `otel.resource.attributes` | empty map | +```shell +export OTEL_PROPAGATORS="tracecontext,b3" +export OTEL_RESOURCE_ATTRIBUTES="environment=dev,xyz=foo" +``` + +##### Native Spring Boot properties style -`otel.resource.attributes` supports a pattern-based resource configuration in -the application.properties like this: +You can also use the native Spring Boot style: + +`application.properties`: ```properties +otel.propagators=tracecontext,b3 otel.resource.attributes.environment=dev otel.resource.attributes.xyz=foo ``` -It's also possible to specify the resource attributes in `application.yaml`: +`application.yaml`: ```yaml otel: + propagators: + - tracecontext + - b3 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" -``` +#### Service name The service name is determined by the following precedence rules, in accordance with the OpenTelemetry From b12306ef6c4a0fb89ac4ee6d060d42c07f3f0273 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Fri, 15 Mar 2024 14:32:58 +0100 Subject: [PATCH 02/10] annotation dependency is included in starter now --- .../languages/java/automatic/spring-boot.md | 30 ------------------- 1 file changed, 30 deletions(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index 8ac3c1cadb52..be0715cdfa00 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -429,36 +429,6 @@ span by annotating the method parameters with `@SpanAttribute`. | ----------- | ------------------------------------------ | ------------- | ------------------ | | `@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-instrumentation-annotations - {{% param vers.instrumentation %}} - - -``` - -{{% /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 From 3d364605db4a5d5ac32adc0789121b08cdd060be Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Fri, 15 Mar 2024 16:10:44 +0100 Subject: [PATCH 03/10] explain advanced config with the example of "exclude actuator endpoints from tracing" --- .../languages/java/automatic/spring-boot.md | 58 ++++++++++++++++++- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index be0715cdfa00..d025916566dc 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -231,6 +231,62 @@ otel: xyz: foo ``` +#### Configuration customizer + +You can use the `AutoConfigurationCustomizerProvider` for programmatic +configuration. Programmatic configuration is recommended for advanced use cases, +which are not configurable via properties. + +##### Exclude actuator endpoints from tracing + +As an example, you can customize the sampler to exclude health check endpoints +from tracing: + +{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} + +```xml + + + io.opentelemetry.contrib + opentelemetry-samplers + 1.33.0-alpha + + +``` + +{{% /tab %}} {{% tab header="Gradle (`gradle.build`)" lang=Gradle %}} + +```kotlin +dependencies { + implementation("io.opentelemetry.contrib:opentelemetry-samplers:1.33.0-alpha") +} +``` + +{{% /tab %}} {{< /tabpane>}} + +```java +import io.opentelemetry.api.trace.SpanKind; +import io.opentelemetry.contrib.sampler.RuleBasedRoutingSampler; +import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider; +import io.opentelemetry.semconv.SemanticAttributes; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +@Configuration +public class Application { + + @Bean + public AutoConfigurationCustomizerProvider otelCustomizer() { + return p -> + p.addSamplerCustomizer( + (fallback, config) -> + RuleBasedRoutingSampler.builder(SpanKind.SERVER, fallback) + .drop(SemanticAttributes.URL_PATH, "^/actuator") + .build()); + } +} +``` + #### Service name The service name is determined by the following precedence rules, in accordance @@ -429,8 +485,6 @@ span by annotating the method parameters with `@SpanAttribute`. | ----------- | ------------------------------------------ | ------------- | ------------------ | | `@WithSpan` | `otel.instrumentation.annotations.enabled` | true | WithSpan, Aspect | -##### Usage - ```java import org.springframework.stereotype.Component; From e504c259a861ec706ca53b06714da544e0568ea7 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Fri, 15 Mar 2024 17:22:25 +0100 Subject: [PATCH 04/10] explain resource providers --- .../languages/java/automatic/spring-boot.md | 107 +++++++++++++++++- 1 file changed, 103 insertions(+), 4 deletions(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index d025916566dc..1d516e1d2833 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -4,7 +4,7 @@ linkTitle: Spring Boot weight: 30 description: Spring Boot instrumentation for OpenTelemetry Java # prettier-ignore -cSpell:ignore: autoconfigurations autoconfigures datasource logback springboot webflux webmvc +cSpell:ignore: autoconfigurations autoconfigures customizer datasource distro logback springboot webflux webmvc --- ## How to instrument Spring Boot with OpenTelemetry @@ -231,7 +231,7 @@ otel: xyz: foo ``` -#### Configuration customizer +#### Programmatic configuration You can use the `AutoConfigurationCustomizerProvider` for programmatic configuration. Programmatic configuration is recommended for advanced use cases, @@ -287,10 +287,109 @@ public class Application { } ``` +#### Resource Providers + +The OpenTelemetry Starter includes +[common Resource Providers](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/resources/library) +and the following Spring Boot specific Resource Providers: + +##### Distribution Resource Provider + +FQN: +`io.opentelemetry.instrumentation.spring.autoconfigure.resources.DistroVersionResourceProvider` + +| Attribute | Value | +| -------------------------- | ----------------------------------- | +| `telemetry.distro.name` | `opentelemetry-spring-boot-starter` | +| `telemetry.distro.version` | version of the starter | + +##### Spring Resource Provider + +FQN: +`io.opentelemetry.instrumentation.spring.autoconfigure.resources.SpringResourceProvider` + +| Attribute | Value | +| ----------------- | ------------------------------------------------------------------------------------------------------------- | +| `service.name` | `spring.application.name` or `build.version` from `build-info.properties` (see [Service name](#service-name)) | +| `service.version` | `build.name` from `build-info.properties` | + +##### AWS Resource Provider + +The +[AWS Resource Provider](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/aws-resources) +can be added as a dependency: + +{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} + +```xml + + + io.opentelemetry.contrib + opentelemetry-aws-resources + 1.33.0-alpha + + + com.fasterxml.jackson.core + jackson-core + + + com.squareup.okhttp3 + okhttp + + + + +``` + +{{% /tab %}} {{% tab header="Gradle (`gradle.build`)" lang=Gradle %}} + +```kotlin +implementation("io.opentelemetry.contrib:opentelemetry-aws-resources:1.33.0-alpha") { + exclude("com.fasterxml.jackson.core", "jackson-core") + exclude("com.squareup.okhttp3", "okhttp") +} +``` + +{{% /tab %}} {{< /tabpane>}} + +##### GCP Resource Provider + +The +[GCP Resource Provider](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/gcp-resources) +can be added as a dependency: + +{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} + +```xml + + + io.opentelemetry.contrib + opentelemetry-gcp-resources + 1.33.0-alpha + + + com.fasterxml.jackson.core + jackson-core + + + + +``` + +{{% /tab %}} {{% tab header="Gradle (`gradle.build`)" lang=Gradle %}} + +```kotlin +implementation("io.opentelemetry.contrib:opentelemetry-gcp-resources:1.33.0-alpha") { + exclude("com.fasterxml.jackson.core", "jackson-core") +} +``` + +{{% /tab %}} {{< /tabpane>}} + #### Service name -The service name is determined by the following precedence rules, in accordance -with the OpenTelemetry +Using these resource providers, 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 From e066061bdf9d387e802b51974bb19ed66c98fc43 Mon Sep 17 00:00:00 2001 From: Jean Bisutti Date: Fri, 15 Mar 2024 21:47:50 +0100 Subject: [PATCH 05/10] Update spring-boot.md --- .../languages/java/automatic/spring-boot.md | 70 ++++++------------- 1 file changed, 21 insertions(+), 49 deletions(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index 1d516e1d2833..4729cfd9346e 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -132,9 +132,6 @@ Add the dependency given below to enable the OpenTelemetry starter. 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](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 %}} @@ -164,61 +161,20 @@ This spring starter supports which means that you can see and autocomplete all available properties in your IDE. -The OpenTelemetry Starter supports all properties from the -[Configuration](/docs/languages/java/automatic/configuration/) page (since -2.2.0). -The only difference is that the OpenTelemetry Spring Boot starter uses -`http/protobuf` as the default protocol for the OTLP exporter (since 2.0.0). +#### General configurations -#### Disable the OpenTelemetry Starter +The OpenTelemetry Starter supports all the [SDK Autoconfiguration](/docs/languages/java/automatic/configuration/#sdk-autoconfiguration) (since +2.2.0). You can use properties set in the `application.properties` or the `application.yaml` file, or environment variables. -{{% config_option name="otel.sdk.disabled" %}} - -Set the value to `true` to disable the starter, e.g. for testing purposes. - -{{% /config_option %}} - -#### Spring Boot properties integration - -All OpenTelemetry properties can be set in the `application.properties` or the -`application.yaml` file. - -Lists and maps can use both the OpenTelemetry and Spring Boot flavors. - -##### OpenTelemetry properties style - -The OpenTelemetry Starter supports the OpenTelemetry properties as described in -the -[specification](/docs/languages/sdk-configuration/general/#otel_resource_attributes): - -`application.properties`: +`application.properties` example: ```properties otel.propagators=tracecontext,b3 otel.resource.attributes=environment=dev,xyz=foo ``` -This style is convenient to use in environment variables: - -```shell -export OTEL_PROPAGATORS="tracecontext,b3" -export OTEL_RESOURCE_ATTRIBUTES="environment=dev,xyz=foo" -``` - -##### Native Spring Boot properties style - -You can also use the native Spring Boot style: - -`application.properties`: - -```properties -otel.propagators=tracecontext,b3 -otel.resource.attributes.environment=dev -otel.resource.attributes.xyz=foo -``` - -`application.yaml`: +`application.yaml` example: ```yaml otel: @@ -231,6 +187,22 @@ otel: xyz: foo ``` + + environment variables example: + +```shell +export OTEL_PROPAGATORS="tracecontext,b3" +export OTEL_RESOURCE_ATTRIBUTES="environment=dev,xyz=foo" +``` + +Disable the OpenTelemetry Starter: + +{{% config_option name="otel.sdk.disabled" %}} + +Set the value to `true` to disable the starter, e.g. for testing purposes. + +{{% /config_option %}} + #### Programmatic configuration You can use the `AutoConfigurationCustomizerProvider` for programmatic From 3fe40120b78dda11b4a7c866dca7b108d7a7ae59 Mon Sep 17 00:00:00 2001 From: Jean Bisutti Date: Fri, 15 Mar 2024 21:48:32 +0100 Subject: [PATCH 06/10] Update spring-boot.md --- content/en/docs/languages/java/automatic/spring-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index 4729cfd9346e..ce414f55c347 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -162,7 +162,7 @@ which means that you can see and autocomplete all available properties in your IDE. -#### General configurations +#### General configuration The OpenTelemetry Starter supports all the [SDK Autoconfiguration](/docs/languages/java/automatic/configuration/#sdk-autoconfiguration) (since 2.2.0). You can use properties set in the `application.properties` or the `application.yaml` file, or environment variables. From 83d4a894b62c9a3c95732ca69d78d6f7aa090c4a Mon Sep 17 00:00:00 2001 From: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Date: Fri, 15 Mar 2024 20:50:10 +0000 Subject: [PATCH 07/10] Results from /fix:format --- .../en/docs/languages/java/automatic/spring-boot.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index ce414f55c347..c8e61513e958 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -161,11 +161,12 @@ This spring starter supports which means that you can see and autocomplete all available properties in your IDE. - #### General configuration -The OpenTelemetry Starter supports all the [SDK Autoconfiguration](/docs/languages/java/automatic/configuration/#sdk-autoconfiguration) (since -2.2.0). You can use properties set in the `application.properties` or the `application.yaml` file, or environment variables. +The OpenTelemetry Starter supports all the +[SDK Autoconfiguration](/docs/languages/java/automatic/configuration/#sdk-autoconfiguration) +(since 2.2.0). You can use properties set in the `application.properties` or the +`application.yaml` file, or environment variables. `application.properties` example: @@ -187,8 +188,7 @@ otel: xyz: foo ``` - - environment variables example: +environment variables example: ```shell export OTEL_PROPAGATORS="tracecontext,b3" From 29c5e5f0dc2d496e965e86a5fecabda336910e10 Mon Sep 17 00:00:00 2001 From: Jean Bisutti Date: Fri, 15 Mar 2024 21:55:02 +0100 Subject: [PATCH 08/10] Update spring-boot.md --- content/en/docs/languages/java/automatic/spring-boot.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index c8e61513e958..86759a7780a2 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -165,8 +165,8 @@ IDE. The OpenTelemetry Starter supports all the [SDK Autoconfiguration](/docs/languages/java/automatic/configuration/#sdk-autoconfiguration) -(since 2.2.0). You can use properties set in the `application.properties` or the -`application.yaml` file, or environment variables. +(since 2.2.0). You can set properties in the `application.properties` or the +`application.yaml` file, or use environment variables. `application.properties` example: From e27c4688b952ba8962975e6bc80a8414c7392bb5 Mon Sep 17 00:00:00 2001 From: Jean Bisutti Date: Fri, 15 Mar 2024 21:55:53 +0100 Subject: [PATCH 09/10] Update content/en/docs/languages/java/automatic/spring-boot.md Co-authored-by: Fabrizio Ferri-Benedetti --- content/en/docs/languages/java/automatic/spring-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index 86759a7780a2..a963a68cf5b3 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -207,7 +207,7 @@ Set the value to `true` to disable the starter, e.g. for testing purposes. You can use the `AutoConfigurationCustomizerProvider` for programmatic configuration. Programmatic configuration is recommended for advanced use cases, -which are not configurable via properties. +which are not configurable using properties. ##### Exclude actuator endpoints from tracing From 91e80e965bb6212979628f6cc9638f5a687c2117 Mon Sep 17 00:00:00 2001 From: Jean Bisutti Date: Fri, 15 Mar 2024 22:05:43 +0100 Subject: [PATCH 10/10] Update spring-boot.md --- content/en/docs/languages/java/automatic/spring-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index a963a68cf5b3..c6ce6b409414 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -188,7 +188,7 @@ otel: xyz: foo ``` -environment variables example: +Environment variables example: ```shell export OTEL_PROPAGATORS="tracecontext,b3"