-
Notifications
You must be signed in to change notification settings - Fork 1.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Reorganize Spring Boot content (#4554)
Co-authored-by: opentelemetrybot <[email protected]> Co-authored-by: Gregor Zeitlinger <[email protected]> Co-authored-by: Phillip Carter <[email protected]>
- Loading branch information
1 parent
18d64cd
commit 90da157
Showing
8 changed files
with
783 additions
and
744 deletions.
There are no files selected for viewing
28 changes: 28 additions & 0 deletions
28
content/en/docs/zero-code/java/spring-boot-starter/_index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
--- | ||
title: Spring Boot starter | ||
aliases: | ||
[ | ||
/docs/languages/java/automatic/spring-boot/, | ||
/docs/zero-code/java/spring-boot/, | ||
] | ||
--- | ||
|
||
You can use two options to instrument | ||
[Spring Boot](https://spring.io/projects/spring-boot) applications with | ||
OpenTelemetry. | ||
|
||
1. The default choice for instrumenting Spring Boot applications is the | ||
[**OpenTelemetry Java agent**](../agent) with byte code instrumentation: | ||
- **More out of the box instrumentation** than the OpenTelemetry starter | ||
2. The **OpenTelemetry Spring Boot starter** can help you with: | ||
- **Spring Boot Native image** applications for which the OpenTelemetry Java | ||
agent does not work | ||
- **Startup overhead** of the OpenTelemetry Java agent exceeding your | ||
requirements | ||
- A Java monitoring agent already used because the OpenTelemetry Java agent | ||
might not work with the other agent | ||
- **Spring Boot configuration files** (`application.properties`, | ||
`application.yml`) to configure the OpenTelemetry Spring Boot starter which | ||
doesn't work with the OpenTelemetry Java agent | ||
|
||
## Use the OpenTelemetry starter |
42 changes: 42 additions & 0 deletions
42
content/en/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,42 @@ | ||
--- | ||
title: Additional instrumentations | ||
description: | ||
Additional instrumentations in addition to the out of the box instrumentation | ||
of the starter | ||
weight: 50 | ||
--- | ||
|
||
The OpenTelemetry Spring Boot starter provides of the box | ||
instrumentation](../out-of-the-box-instrumentation) that you can complete with | ||
additional instrumentations. | ||
|
||
## Log4j2 Instrumentation | ||
|
||
You have to add the OpenTelemetry appender to your `log4j2.xml` file: | ||
|
||
```xml | ||
<?xml version="1.0" encoding="UTF-8"?> | ||
<Configuration status="WARN" packages="io.opentelemetry.instrumentation.log4j.appender.v2_17"> | ||
<Appenders> | ||
<OpenTelemetry name="OpenTelemetryAppender"/> | ||
</Appenders> | ||
<Loggers> | ||
<Root> | ||
<AppenderRef ref="OpenTelemetryAppender" level="All"/> | ||
</Root> | ||
</Loggers> | ||
</Configuration> | ||
``` | ||
|
||
You can find more configuration options for the OpenTelemetry appender in the | ||
[Log4j](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/log4j/log4j-appender-2.17/library/README.md) | ||
instrumentation library. | ||
|
||
| System property | Type | Default | Description | | ||
| --------------------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------- | | ||
| `otel.instrumentation.log4j-appender.enabled` | Boolean | true | Enables the configuration of the Log4j OpenTelemetry appender with an `OpenTelemetry` instance. | | ||
|
||
## 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). |
59 changes: 59 additions & 0 deletions
59
content/en/docs/zero-code/java/spring-boot-starter/annotations.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,59 @@ | ||
--- | ||
title: Annotations | ||
description: Using instrumentation annotations with the Spring starter. | ||
aliases: [../annotations] | ||
weight: 60 | ||
--- | ||
|
||
For most users, the out-of-the-box instrumentation is completely sufficient and | ||
nothing more has to be done. Sometimes, however, users wish to create | ||
[spans](/docs/concepts/signals/traces/#spans) for their own custom code without | ||
doing too much code change. | ||
|
||
## Available 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. To learn more about aspect weaving in spring, see | ||
> [spring-aop](https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#aop). | ||
| Feature | Property | Default Value | Description | | ||
| ----------- | ------------------------------------------ | ------------- | --------------------------------- | | ||
| `@WithSpan` | `otel.instrumentation.annotations.enabled` | true | Enables the WithSpan annotations. | | ||
|
||
```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) { | ||
} | ||
} | ||
``` |
132 changes: 132 additions & 0 deletions
132
content/en/docs/zero-code/java/spring-boot-starter/getting-started.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,132 @@ | ||
--- | ||
title: Getting Started | ||
description: Getting Started of the OpenTelemetry starter | ||
weight: 20 | ||
cSpell:ignore: springboot | ||
--- | ||
|
||
## OpenTelemetry Spring Boot starter | ||
|
||
{{% alert title="Note" color="info" %}} | ||
|
||
You can also use the Java agent to instrument your Spring Boot application. The | ||
pros and cons are described in the [overview page](..). | ||
|
||
{{% /alert %}} | ||
|
||
### Compatibility | ||
|
||
The OpenTelemetry Spring Boot starter works with Spring Boot 2.0 and 3.0, and | ||
Spring Boot native image applications. The | ||
[opentelemetry-java-examples/spring-native](https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/spring-native) | ||
repository contains an example of a Spring Boot Native image application | ||
instrumented using the OpenTelemetry Spring Boot starter. | ||
|
||
### Dependency management | ||
|
||
A Bill of Material | ||
([BOM](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#bill-of-materials-bom-poms)) | ||
ensures that versions of dependencies (including transitive ones) are aligned. | ||
|
||
Importing the `opentelemetry-bom` and `opentelemetry-instrumentation-bom-alpha` | ||
BOMs when using the OpenTelemetry starter is important to ensure version | ||
alignment across all OpenTelemetry dependencies. | ||
|
||
The following example shows how to import both BOMs using Maven: | ||
|
||
```xml | ||
<dependencyManagement> | ||
<dependencies> | ||
<dependency> | ||
<groupId>io.opentelemetry</groupId> | ||
<artifactId>opentelemetry-bom</artifactId> | ||
<version>{{% param vers.otel %}}</version> | ||
<type>pom</type> | ||
<scope>import</scope> | ||
</dependency> | ||
<dependency> | ||
<groupId>io.opentelemetry.instrumentation</groupId> | ||
<artifactId>opentelemetry-instrumentation-bom-alpha</artifactId> | ||
<version>{{% param vers.instrumentation %}}-alpha</version> | ||
<type>pom</type> | ||
<scope>import</scope> | ||
</dependency> | ||
</dependencies> | ||
</dependencyManagement> | ||
``` | ||
|
||
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`: | ||
|
||
```kotlin | ||
import org.springframework.boot.gradle.plugin.SpringBootPlugin | ||
|
||
plugins { | ||
id("java") | ||
id("org.springframework.boot") version "3.2.O" | ||
} | ||
|
||
dependencies { | ||
implementation(platform(SpringBootPlugin.BOM_COORDINATES)) | ||
implementation(platform("io.opentelemetry:opentelemetry-bom:{{% param vers.otel %}}")) | ||
implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:{{% param vers.instrumentation %}}-alpha")) | ||
} | ||
``` | ||
|
||
The other way with Gradle is to use the `io.spring.dependency-management` plugin | ||
and to import the BOMs in `dependencyManagement`: | ||
|
||
```kotlin | ||
plugins { | ||
id("java") | ||
id("org.springframework.boot") version "3.2.O" | ||
id("io.spring.dependency-management") version "1.1.0" | ||
} | ||
|
||
dependencyManagement { | ||
imports { | ||
mavenBom("io.opentelemetry:opentelemetry-bom:{{% param vers.otel %}}") | ||
mavenBom("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:{{% param vers.instrumentation %}}-alpha") | ||
} | ||
} | ||
``` | ||
|
||
{{% alert title="Note" color="info" %}} | ||
|
||
Be careful not to mix up the different ways of configuring things with Gradle. | ||
For example, don't use | ||
`implementation(platform("io.opentelemetry:opentelemetry-bom:{{% param vers.otel %}}"))` | ||
with the `io.spring.dependency-management` plugin. | ||
|
||
{{% /alert %}} | ||
|
||
#### OpenTelemetry Starter dependency | ||
|
||
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). | ||
|
||
{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} | ||
|
||
```xml | ||
<dependencies> | ||
<dependency> | ||
<groupId>io.opentelemetry.instrumentation</groupId> | ||
<artifactId>opentelemetry-spring-boot-starter</artifactId> | ||
</dependency> | ||
</dependencies> | ||
``` | ||
|
||
{{% /tab %}} {{% tab header="Gradle (`gradle.build`)" lang=Gradle %}} | ||
|
||
```kotlin | ||
dependencies { | ||
implementation("io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter") | ||
} | ||
``` | ||
|
||
{{% /tab %}} {{< /tabpane>}} |
70 changes: 70 additions & 0 deletions
70
content/en/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,70 @@ | ||
--- | ||
title: Other Spring autoconfigurations | ||
description: Spring autoconfigurations without the OpenTelemetry Spring starter | ||
cSpell:ignore: autoconfigurations | ||
weight: 70 | ||
--- | ||
|
||
Instead of using the OpenTelemetry Spring starter, you can use the OpenTelemetry | ||
autoconfiguration features with an annotation or the Zipkin starter. | ||
|
||
## Spring support | ||
|
||
Autoconfiguration is natively supported by Spring Boot 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 autoconfiguration. 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` | |
Oops, something went wrong.