Improve OpenTelemetry Java manual instrumentation documentation (#19424)

* Improve OpenTelemetry Javan manual instrumentation documentation * Fix case Co-authored-by: Brett Blue <[email protected]> * Addressing Vale check Co-authored-by: Brett Blue <[email protected]> * Improve wording Co-authored-by: Brett Blue <[email protected]> * Add OTel instrumentation annotation support * Remove confusing SDK reference and minor cleanups --------- Co-authored-by: Brett Blue <[email protected]> Co-authored-by: Björn Antonsson <[email protected]>
DataDog · Jan 17, 2024 · b7a052e · b7a052e
1 parent 732d101
commit b7a052e
Showing 1 changed file with 108 additions and 18 deletions.
diff --git a/content/en/tracing/trace_collection/otel_instrumentation/java.md b/content/en/tracing/trace_collection/otel_instrumentation/java.md
@@ -22,35 +22,125 @@ further_reading:
 
 The following OpenTelemetry features implemented in the Datadog library as noted:
 
-| Feature                               | Support notes                       |
-|---------------------------------------|-------------------------------------------|
-| [OpenTelemetry Context propagation][1]         | [Datadog and W3C Trace Context header formats][9] are enabled by default. | 
-| [Span processors][2]                  | Unsupported                                          | 
-| [Span Exporters][3]                   | Unsupported                                            |
-| Trace/span [ID generators][4]         | ID generation is performed by the tracing library, with support for [128-bit trace IDs][12].    |
-
+| Feature                                           | Support notes                                                                               |
+|---------------------------------------------------|---------------------------------------------------------------------------------------------|
+| [OpenTelemetry Context propagation][1]            | [Datadog distributed header format][2] is used instead by default.                          |
+| [Span processors][3]                              | Unsupported                                                                                 |
+| [Span Exporters][4]                               | Unsupported                                                                                 |
+| Trace/span [ID generators][5]                     | ID generation is performed by the tracing library, with support for [128-bit trace IDs][6]. |
+| [Metrics][7], [Baggage][8] and [Context][9] API   | Unsupported                                                                                 |
 
 ## Configuring OpenTelemetry to use the Datadog tracing library
 
-1. Add your desired manual OpenTelemetry instrumentation to your Java code following the [OpenTelemetry Java Manual Instrumentation documentation][5]. **Important!** Where those instructions indicate that your code should call the OpenTelemetry SDK, call the Datadog tracing library instead.
+<div class="alert alert-info">
+If you have not yet read the instructions for auto-instrumentation and setup, start with the <a href="https://docs.datadoghq.com/tracing/setup/java/">Java Setup Instructions</a>.
+</div>
+
+1. Add your desired manual OpenTelemetry instrumentation to your Java code following the [OpenTelemetry Java Manual Instrumentation documentation][10].
+
+1. Add the [Datadog tracing library to the JVM][11]. **Beta:** You can optionally do this with [One-Step APM Instrumentation][12].
+
+1. Make sure you only depend on the OpenTelemetry API (and not the OpenTelemetry SDK).
+
+{{< tabs >}}
+{{% tab "Gradle" %}}
+
+{{< code-block lang="groovy" >}}
+// OpenTelemetry API
+implementation "io.opentelemetry:opentelemetry-api:${opentelemetryVersion}"
+{{< /code-block >}}
 
-1. Add the [Datadog tracing library to the JVM][11]. **Beta:** You can optionally do this with [One-Step APM Instrumentation][13].
+{{% /tab %}}
+{{% tab "Maven" %}}
 
-1. Set the `dd.trace.otel.enabled` system property to `true`.
+{{< code-block lang="xml" >}}
+<!-- OpenTelemetry API -->
+<dependency>
+        <groupId>io.opentelemetry</groupId>
+        <artifactId>opentelemetry-api</artifactId>
+        <version>${io.opentelemtry.version}</version>
+    </dependency>
+<dependency>
+{{< /code-block >}}
+
+{{% /tab %}}
+{{< /tabs >}}
+
+1. Set the `dd.trace.otel.enabled` system property or the `DD_TRACE_OTEL_ENABLED` environment variable to `true`.
 
 Datadog combines these OpenTelemetry spans with other Datadog APM spans into a single trace of your application.
 
+
+## Common use cases
+
+### Add custom attributes to the current or local root span
+
+```java
+// Add attributes to the current span
+Span currentSpan = Span.current();
+currentSpan.setAttributes("some-key", "some-value");
+
+// Add attributes to the local root span
+ContextKey<OtelSpan> localRootSpanKey = ContextKey.named("datadog-root-span-key");
+Span rootSpan = Context.current().get(localRootSpanKey);
+rootSpan.setAttributes("some-key", "some-value");
+```
+
+**Note:** If there isn't a current or local root span, the returned span is invalid, not `null`, and attributes are not set.
+
+### Add custom spans using annotations
+
+First add a dependency to the `opentelemetry-instrumentation-annotations` library.
+
+{{< tabs >}}
+{{% tab "Gradle" %}}
+
+{{< code-block lang="groovy" >}}
+  // OpenTelemetry instrumentation annotations
+  implementation "io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:${opentelemetryVersion}"
+{{< /code-block >}}
+
+{{% /tab %}}
+{{% tab "Maven" %}}
+
+{{< code-block lang="xml" >}}
+<!-- OpenTelemetry instrumentation annotations -->
+<dependency>
+        <groupId>io.opentelemetry.instrumentation</groupId>
+        <artifactId>opentelemetry-instrumentation-annotations</artifactId>
+        <version>${io.opentelemtry.version}</version>
+    </dependency>
+<dependency>
+{{< /code-block >}}
+
+{{% /tab %}}
+{{< /tabs >}}
+
+Then annotate your methods with the `@WithSpan` annotation to create a new span each call. The parameters of the call can be annotated with the `@SpanAttribute` annotation to capture the arguments as span attributes:
+
+```java
+@WithSpan
+public void myMethod(@SpanAttribute("parameter1") String parameter1,
+    @SpanAttribute("parameter2") long parameter2) {
+    <...>
+}
+```
+
+**Note:** Using the `@AddingSpanAttributes` method annotation instead of `@WithSpan` allows capturing method arguments using the `@SpanAttribute` annotation without creating a new span. The current span, if it exists, is going to be updated with the captured arguments.
+
 ## Further Reading
 
 {{< partial name="whats-next/whats-next.html" >}}
 
 [1]: https://opentelemetry.io/docs/instrumentation/java/manual/#context-propagation
-[2]: https://opentelemetry.io/docs/reference/specification/trace/sdk/#span-processor
-[3]: https://opentelemetry.io/docs/reference/specification/trace/sdk/#span-exporter
-[4]: https://opentelemetry.io/docs/reference/specification/trace/sdk/#id-generators
-[5]: https://opentelemetry.io/docs/instrumentation/java/manual/
-[8]: https://opentelemetry.io/docs/instrumentation/java/automatic/
-[9]: /tracing/trace_collection/trace_context_propagation/java/
+[2]: /tracing/trace_collection/trace_context_propagation/java/
+[3]: https://opentelemetry.io/docs/reference/specification/trace/sdk/#span-processor
+[4]: https://opentelemetry.io/docs/reference/specification/trace/sdk/#span-exporter
+[5]: https://opentelemetry.io/docs/reference/specification/trace/sdk/#id-generators
+[6]: /opentelemetry/guide/otel_api_tracing_interoperability/
+[7]: https://opentelemetry.io/docs/specs/otel/metrics/api/
+[8]: https://opentelemetry.io/docs/specs/otel/baggage/api/
+[9]: https://opentelemetry.io/docs/specs/otel/context/
+[10]: https://opentelemetry.io/docs/instrumentation/java/manual/
 [11]: /tracing/trace_collection/dd_libraries/java/?tab=springboot#add-the-java-tracer-to-the-jvm
-[12]: /opentelemetry/guide/otel_api_tracing_interoperability/
-[13]: /tracing/trace_collection/single-step-apm/
+[12]: /tracing/trace_collection/single-step-apm/