Skip to content

Commit

Permalink
Reorganize Spring Boot content (#4554)
Browse files Browse the repository at this point in the history
Co-authored-by: opentelemetrybot <[email protected]>
Co-authored-by: Gregor Zeitlinger <[email protected]>
Co-authored-by: Phillip Carter <[email protected]>
  • Loading branch information
4 people authored May 30, 2024
1 parent 18d64cd commit 90da157
Show file tree
Hide file tree
Showing 8 changed files with 783 additions and 744 deletions.
28 changes: 28 additions & 0 deletions content/en/docs/zero-code/java/spring-boot-starter/_index.md
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
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 content/en/docs/zero-code/java/spring-boot-starter/annotations.md
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 content/en/docs/zero-code/java/spring-boot-starter/getting-started.md
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>}}
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` |
Loading

0 comments on commit 90da157

Please sign in to comment.