Improve the annotation doc of the OTel starter (#4806)

Co-authored-by: Tiffany Hrabusa <[email protected]> Co-authored-by: Jay DeLuca <[email protected]>
open-telemetry · Jul 10, 2024 · 2faf0ea · 2faf0ea
1 parent be65f15
commit 2faf0ea
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 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
@@ -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
@@ -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
+<dependencies>
+  <dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>>spring-boot-starter-aop</artifactId>
+  </dependency>
+</dependencies>
+```
+
+{{% /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
@@ -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"