From 2faf0ea68ab12d5fc5423fc98031a3d287b3f88e Mon Sep 17 00:00:00 2001 From: Jean Bisutti Date: Wed, 10 Jul 2024 16:14:26 +0200 Subject: [PATCH] Improve the annotation doc of the OTel starter (#4806) Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com> Co-authored-by: Jay DeLuca --- .../additional-instrumentations.md | 2 +- .../java/spring-boot-starter/annotations.md | 108 ++++++++++++------ static/refcache.json | 4 + 3 files changed, 78 insertions(+), 36 deletions(-) diff --git a/content/en/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md b/content/en/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md index 241b180ac0eb..a3faeb0cff8a 100644 --- a/content/en/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md +++ b/content/en/docs/zero-code/java/spring-boot-starter/additional-instrumentations.md @@ -1,6 +1,6 @@ --- title: Additional instrumentation -weight: 50 +weight: 60 --- The OpenTelemetry Spring Boot starter provides diff --git a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md index 3d3b9ce0b518..23587a81641e 100644 --- a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md +++ b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md @@ -1,57 +1,95 @@ --- title: Annotations -weight: 60 +weight: 50 +cSpell:ignore: proxys --- 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. +needing to make many code changes. -## 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. | +If you add the `WithSpan` annotation to a method, the method is wrapped in a +span. The `SpanAttribute` annotation allows you to capture the method arguments +as attributes. ```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() { + public void tracedMethod(@SpanAttribute parameter) { } +``` - @WithSpan(value="span name") - public void tracedMethodWithName() { - Span currentSpan = Span.current(); - currentSpan.addEvent("ADD EVENT TO tracedMethodWithName SPAN"); - currentSpan.setAttribute("isTestAttribute", true); - } +{{% alert title="Note" color="info" %}} The OpenTelemetry annotations use Spring +AOP based on proxys. + +These annotations work only for the methods of the proxy. You can learn more in +the +[Spring documentation](https://docs.spring.io/spring-framework/reference/core/aop/proxying.html). - @WithSpan(kind = SpanKind.CLIENT) - public void tracedClientSpan() { +In the following example, the `WithSpan` annotation won't do anything when the +GET endpoint is called: + +```java +@RestController +public class MyControllerManagedBySpring { + + @GetMapping("/ping") + public void aMethod() { + anotherMethod(); } - public void tracedMethodWithAttribute(@SpanAttribute("attributeName") String parameter) { + @WithSpan + public void anotherMethod() { } } ``` + +{{% /alert %}} + +{{% alert title="Note" color="info" %}} + +To be able to use the OpenTelemetry annotations, you have to add the Spring Boot +Starter AOP dependency to your project: + +{{< tabpane text=true >}} {{% tab header="Maven (`pom.xml`)" lang=Maven %}} + +```xml + + + org.springframework.boot + >spring-boot-starter-aop + + +``` + +{{% /tab %}} {{% tab header="Gradle (`gradle.build`)" lang=Gradle %}} + +```kotlin +dependencies { + implementation("org.springframework.boot:spring-boot-starter-aop") +} +``` + +{{% /tab %}} {{< /tabpane >}} + +{{% /alert %}} + +You can disable the OpenTelemetry annotations by setting the +`otel.instrumentation.annotations.enabled` property to `false`. + +You can customize the span by using the elements of the `WithSpan` annotation: + +| Name | Type | Description | Default Value | +| ------- | ---------- | --------------------- | ------------------- | +| `value` | `String` | Span name | ClassName.Method | +| `kind` | `SpanKind` | Span kind of the span | `SpanKind.INTERNAL` | + +You can set the attribute name from the `value` element of the `SpanAttribute` +annotation: + +| Name | Type | Description | Default Value | +| ------- | -------- | -------------- | --------------------- | +| `value` | `String` | Attribute name | Method parameter name | diff --git a/static/refcache.json b/static/refcache.json index ba0920283c4e..8cd9a9c7f57c 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -1747,6 +1747,10 @@ "StatusCode": 206, "LastSeen": "2024-04-03T12:51:54.758528517+02:00" }, + "https://docs.spring.io/spring-framework/reference/core/aop/proxying.html": { + "StatusCode": 206, + "LastSeen": "2024-07-09T08:58:07.531333949Z" + }, "https://docs.spring.io/spring-security/reference/servlet/authorization/architecture.html#authz-authorities": { "StatusCode": 206, "LastSeen": "2024-02-12T22:02:33.483262-05:00"