Skip to content

Commit

Permalink
Spring starter 2.1.0 (#4026)
Browse files Browse the repository at this point in the history 
Co-authored-by: Jean Bisutti <[email protected]>
Co-authored-by: opentelemetrybot <[email protected]>
  • Loading branch information
@zeitlinger @jeanbisutti @opentelemetrybot
3 people authored Feb 20, 2024
1 parent 855d651 commit 4a4d2e7
Show file tree
Hide file tree
Showing 2 changed files with 88 additions and 78 deletions.
162 changes: 84 additions & 78 deletions content/en/docs/languages/java/automatic/spring-boot.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>
%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
</pattern>
</encoder>
</appender>
<appender name="OpenTelemetry"
class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender ">
<captureExperimentalAttributes>false</captureExperimentalAttributes>
<captureCodeAttributes>true</captureCodeAttributes>
<captureMarkerAttribute>true</captureMarkerAttribute>
<captureKeyValuePairAttributes>true</captureKeyValuePairAttributes>
<captureLoggerContext>true</captureLoggerContext>
<captureMdcAttributes>*</captureMdcAttributes>
</appender>
<root level="INFO">
<appender-ref ref="console"/>
<appender-ref ref="OpenTelemetry"/>
</root>
</configuration>
```

#### Spring Web Autoconfiguration

Expand Down Expand Up @@ -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
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
<encoder>
<pattern>
%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
</pattern>
</encoder>
</appender>
<appender name="OpenTelemetry"
class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">
</appender>
<root level="INFO">
<appender-ref ref="console"/>
<appender-ref ref="OpenTelemetry"/>
</root>
</configuration>
```
#### 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
<?xml version="1.0" encoding="UTF-8"?>
Expand All @@ -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

Expand Down Expand Up @@ -427,8 +433,8 @@ span by annotating the method parameters with `@SpanAttribute`.
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-extension-annotations</artifactId>
<version>{{% param vers.otel %}}</version>
<artifactId>opentelemetry-instrumentation-annotations</artifactId>
<version>{{% param vers.instrumentation %}}</version>
</dependency>
</dependencies>
```
Expand Down
4 changes: 4 additions & 0 deletions static/refcache.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down

0 comments on commit 4a4d2e7

Please sign in to comment.