open-telemetry
/
opentelemetry.io
mirror of https://github.com/open-telemetry/opentelemetry.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Spring starter 2.1.0 (#4026) 

Co-authored-by: Jean Bisutti <jean.bisutti@gmail.com>
Co-authored-by: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com>
This commit is contained in:
Gregor Zeitlinger 2024-02-20 02:16:29 +01:00 committed by GitHub
parent 855d651bdd
commit 4a4d2e722a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 88 additions and 78 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

162
content/en/docs/languages/java/automatic/spring-boot.md
View File

@ -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
#### OpenTelemetry Data Exporters
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.
This package provides autoconfiguration the following 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/).
- OTLP
- Logging
#### Enabling/Disabling Exporters
All available properties are listed in the
[Configuration](/docs/languages/java/automatic/configuration/) page.
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.
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+).
| 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
#### 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 | 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` |
| 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 :
| 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
@ -351,33 +384,9 @@ dependencies {
{{% /tab %}} {{< /tabpane>}}
#### Logging Instrumentation
#### Log4j2 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>
```
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"?>
@ -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`.
</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>
```

4
static/refcache.json
View File

@ -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"