From 4a4d2e722a25011acbb0e2a177fcb44d5aa93016 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Tue, 20 Feb 2024 02:16:29 +0100 Subject: [PATCH] Spring starter 2.1.0 (#4026) Co-authored-by: Jean Bisutti Co-authored-by: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> --- .../languages/java/automatic/spring-boot.md | 162 +++++++++--------- static/refcache.json | 4 + 2 files changed, 88 insertions(+), 78 deletions(-) diff --git a/content/en/docs/languages/java/automatic/spring-boot.md b/content/en/docs/languages/java/automatic/spring-boot.md index 385cea2903b7..b58b8c8adc86 100644 --- a/content/en/docs/languages/java/automatic/spring-boot.md +++ b/content/en/docs/languages/java/automatic/spring-boot.md @@ -35,7 +35,7 @@ You can use [OpenTelemetry instrumentations libraries](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks) to complete the automatic instrumentation of the Spring Boot starter. -## OpenTelemetry starter Spring Boot starter +## OpenTelemetry Spring Boot starter ### Compatibility @@ -157,53 +157,46 @@ dependencies { {{% /tab %}} {{< /tabpane>}} -#### Disable data export +### Configuration + +This spring starter supports +[configuration metadata](https://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html), +which means that you can see and autocomplete all available properties in your +IDE. + +#### Disable the OpenTelemetry Starter {{% config_option name="otel.sdk.disabled" %}} -Set the value to `true` to disable data export, e.g. for testing purposes. +Set the value to `true` to disable the starter, e.g. for testing purposes. {{% /config_option %}} -### 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. +#### OpenTelemetry Data 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/). +This package provides autoconfiguration the following exporters: -#### Enabling/Disabling Exporters +- OTLP +- Logging -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. +All available properties are listed in the +[Configuration](/docs/languages/java/automatic/configuration/) page. -| 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` | +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+). -### Tracer Properties +#### Tracer Properties | Feature | Property | Default Value | | ------- | --------------------------------- | ------------- | | Tracer | `otel.traces.sampler.probability` | 1.0 | -### Resource Properties +#### Resource Properties -| Feature | Property | Default Value | -| -------- | ----------------------------------------------------------------------- | ------------- | -| Resource | `otel.springboot.resource.enabled` | true | -| | `otel.resource.attributes` (old: `otel.springboot.resource.attributes`) | empty map | +| Feature | Property | Default Value | +| -------- | ---------------------------------- | ------------- | +| Resource | `otel.springboot.resource.enabled` | true | +| | `otel.resource.attributes` | empty map | `otel.resource.attributes` supports a pattern-based resource configuration in the application.properties like this: @@ -239,25 +232,65 @@ with the OpenTelemetry 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) +3. `spring.application.name` spring property +4. 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. +Automatic instrumentation is available for several frameworks: + +| Feature | Property | Default Value | +| -------------- | ----------------------------------------------- | ------------- | +| Logback | `otel.instrumentation.logback-appender.enabled` | true | +| Spring Web | `otel.instrumentation.spring-web.enabled` | true | +| Spring Web MVC | `otel.instrumentation.spring-webmvc.enabled` | true | +| Spring WebFlux | `otel.instrumentation.spring-webflux.enabled` | true | + +#### Logback + +You can enable experimental features with system properties to capture +attributes : -| 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` | +| System property | Type | Default | Description | +| -------------------------------------------------------------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --- | +| `otel.instrumentation.logback-appender.experimental-log-attributes` | Boolean | false | Enable the capture of experimental log attributes `thread.name` and `thread.id`. | | +| `otel.instrumentation.logback-appender.experimental.capture-code-attributes` | Boolean | false | Enable the capture of [source code attributes]. Note that capturing source code attributes at logging sites might add a performance overhead. | +| `otel.instrumentation.logback-appender.experimental.capture-marker-attribute` | Boolean | false | Enable the capture of Logback markers as attributes. | +| `otel.instrumentation.logback-appender.experimental.capture-key-value-pair-attributes` | Boolean | false | Enable the capture of Logback key value pairs as attributes. | +| `otel.instrumentation.logback-appender.experimental.capture-logger-context-attributes` | Boolean | false | Enable the capture of Logback logger context properties as attributes. | +| `otel.instrumentation.logback-appender.experimental.capture-mdc-attributes` | String | | Comma separated list of MDC attributes to capture. Use the wildcard character `*` to capture all attributes. | + +[source code attributes]: + https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#source-code-attributes + +Alternatively, you can enable these features by adding the OpenTelemetry Logback +appender in your `logback.xml` or `logback-spring.xml` file: + +```xml + + + + + + %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n + + + + + false + true + true + true + true + * + + + + + + +``` #### Spring Web Autoconfiguration @@ -351,33 +384,9 @@ dependencies { {{% /tab %}} {{< /tabpane>}} -#### 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: - -```xml - - - - - - %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n - - - - - - - - - - -``` +#### Log4j2 Instrumentation -For Log4j 2, you have to add the OpenTelemetry appender to your `log4j2.xml` -file: +You have to add the OpenTelemetry appender to your `log4j2.xml` file: ```xml @@ -394,11 +403,8 @@ file: ``` You can find more configuration options for the OpenTelemetry appender in the -documentation of the -[Logback](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/logback/logback-appender-1.0/library/README.md) -and [Log4j](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/log4j/log4j-appender-2.17/library/README.md) -instrumentation libraries. +instrumentation library. #### Instrumentation Annotations @@ -427,8 +433,8 @@ span by annotating the method parameters with `@SpanAttribute`. io.opentelemetry - opentelemetry-extension-annotations - {{% param vers.otel %}} + opentelemetry-instrumentation-annotations + {{% param vers.instrumentation %}} ``` diff --git a/static/refcache.json b/static/refcache.json index a6bb7fe92b9e..8dc0ec6aa29b 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -1511,6 +1511,10 @@ "StatusCode": 206, "LastSeen": "2024-01-30T16:15:09.437464-05:00" }, + "https://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html": { + "StatusCode": 206, + "LastSeen": "2024-02-19T17:27:38.673604461+01:00" + }, "https://docs.spring.io/spring-boot/docs/current/reference/html/using.html#using.auto-configuration": { "StatusCode": 206, "LastSeen": "2024-01-30T16:15:14.908906-05:00"