update spring boot docs

open-telemetry · Jan 31, 2024 · de79c96 · de79c96
1 parent 4afa92a
commit de79c96
Show file tree

Hide file tree

Showing 2 changed files with 290 additions and 12 deletions.
diff --git 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
+<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
+
+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
+<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` |
diff --git 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"