133 lines
5.4 KiB
Markdown
133 lines
5.4 KiB
Markdown
---
|
|
title: Annotations
|
|
description: Using instrumentation annotations with a Java agent.
|
|
aliases: [../annotations]
|
|
weight: 20
|
|
cSpell:ignore: Flowable javac reactivestreams reactivex
|
|
---
|
|
|
|
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.
|
|
|
|
## Dependencies
|
|
|
|
You'll need to add a dependency on the
|
|
`opentelemetry-instrumentation-annotations` library to use the `@WithSpan`
|
|
annotation.
|
|
|
|
### Maven
|
|
|
|
```xml
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>io.opentelemetry.instrumentation</groupId>
|
|
<artifactId>opentelemetry-instrumentation-annotations</artifactId>
|
|
<version>{{% param vers.instrumentation %}}</version>
|
|
</dependency>
|
|
</dependencies>
|
|
```
|
|
|
|
### Gradle
|
|
|
|
```groovy
|
|
dependencies {
|
|
implementation('io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations:{{% param vers.instrumentation %}}')
|
|
}
|
|
```
|
|
|
|
## Creating spans around methods with `@WithSpan`
|
|
|
|
To create a [span](/docs/concepts/signals/traces/#spans) corresponding to one of
|
|
your method, annotate the method with `@WithSpan`.
|
|
|
|
```java
|
|
import io.opentelemetry.instrumentation.annotations.WithSpan;
|
|
|
|
public class MyClass {
|
|
@WithSpan
|
|
public void myMethod() {
|
|
<...>
|
|
}
|
|
}
|
|
```
|
|
|
|
Each time the application invokes the annotated method, it creates a span that
|
|
denotes its duration and provides any thrown exceptions. By default, the span
|
|
name will be `<className>.<methodName>`, unless a name is provided as an
|
|
argument to the annotation.
|
|
|
|
If the return type of the method annotated by `@WithSpan` is one of the
|
|
[future- or promise-like](https://en.wikipedia.org/wiki/Futures_and_promises)
|
|
types listed below, then the span will not be ended until the future completes.
|
|
|
|
- [java.util.concurrent.CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)
|
|
- [java.util.concurrent.CompletionStage](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletionStage.html)
|
|
- [com.google.common.util.concurrent.ListenableFuture](https://guava.dev/releases/10.0/api/docs/com/google/common/util/concurrent/ListenableFuture.html)
|
|
- [org.reactivestreams.Publisher](https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Publisher.html)
|
|
- [reactor.core.publisher.Mono](https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html)
|
|
- [reactor.core.publisher.Flux](https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Flux.html)
|
|
- [io.reactivex.Completable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Completable.html)
|
|
- [io.reactivex.Maybe](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Maybe.html)
|
|
- [io.reactivex.Single](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Single.html)
|
|
- [io.reactivex.Observable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Observable.html)
|
|
- [io.reactivex.Flowable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/Flowable.html)
|
|
- [io.reactivex.parallel.ParallelFlowable](https://reactivex.io/RxJava/2.x/javadoc/index.html?io/reactivex/parallel/ParallelFlowable.html)
|
|
|
|
## Adding attributes to the span with `@SpanAttribute`
|
|
|
|
When a [span](/docs/concepts/signals/traces/#spans) is created for an annotated
|
|
method the values of the arguments to the method invocation can be automatically
|
|
added as [attributes](/docs/concepts/signals/traces/#attributes) to the created
|
|
span by annotating the method parameters with the `@SpanAttribute` annotation.
|
|
|
|
```java
|
|
import io.opentelemetry.instrumentation.annotations.SpanAttribute;
|
|
import io.opentelemetry.instrumentation.annotations.WithSpan;
|
|
|
|
public class MyClass {
|
|
|
|
@WithSpan
|
|
public void myMethod(@SpanAttribute("parameter1") String parameter1,
|
|
@SpanAttribute("parameter2") long parameter2) {
|
|
<...>
|
|
}
|
|
}
|
|
```
|
|
|
|
Unless specified as an argument to the annotation, the attribute name will be
|
|
derived from the formal parameter names if they are compiled into the `.class`
|
|
files by passing the `-parameters` option to the `javac` compiler.
|
|
|
|
## Suppressing `@WithSpan` instrumentation
|
|
|
|
Suppressing `@WithSpan` is useful if you have code that is over-instrumented
|
|
using `@WithSpan` and you want to suppress some of them without modifying the
|
|
code.
|
|
|
|
{{% config_option
|
|
name="otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methods" %}}
|
|
Suppress `@WithSpan` instrumentation for specific methods. Format is `my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`.
|
|
{{% /config_option %}}
|
|
|
|
## Creating spans around methods with `otel.instrumentation.methods.include`
|
|
|
|
In cases where you are unable to modify the code, you can still configure the
|
|
Java agent to capture spans around specific methods.
|
|
|
|
{{% config_option name="otel.instrumentation.methods.include" %}} Add
|
|
instrumentation for specific methods in lieu of `@WithSpan`. Format is
|
|
`my.package.MyClass1[method1,method2];my.package.MyClass2[method3]`. {{%
|
|
/config_option %}}
|
|
|
|
If a method is overloaded (appears more than once on the same class with the
|
|
same name but different parameters), all versions of the method will be
|
|
instrumented.
|
|
|
|
## Next steps
|
|
|
|
Beyond the use of annotations, the OpenTelemetry API allows you to obtain a
|
|
tracer that can be used for [Manual Instrumentation](../../instrumentation) and
|
|
execute code within the scope of that span.
|