Manual instrumentation

For most users, the out-of-the-box instrumentation is completely sufficient and nothing more has to
be done. Sometimes, however, users wish to add attributes to the otherwise automatic spans,
or they might want to manually create spans for their own custom code.

对于大多数用户来说，开箱即用的工具是完全足够的，不需要再做什么。 然而，有时候，用户希望为自动生成的span添加属性，或者他们可能希望为自己的自定义代码手动创建span。

Dependencies

prior to version 1.0.0, opentelemetry-javaagent-all.jar
only supports manual instrumentation using the opentelemetry-api version with the same version
number as the Java agent you are using. Starting with 1.0.0, the Java agent will start supporting
multiple (1.0.0+) versions of opentelemetry-api. 在1.0.0版本之前，opentelemetry-javaagent-all.jar只支持使用与你所使用的Java代理的版本号相同的opentelemetry-api版本进行手动测量。从1.0.0开始，Java代理将开始支持多个（1.0.0以上）版本的opentelemetry-api。

You’ll need to add a dependency on the opentelemetry-api library to get started; if you intend to
use the @WithSpan annotation, also include the opentelemetry-extension-annotations dependency.

Maven

  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
      <version>1.0.0</version>
    </dependency>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-extension-annotations</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>

Gradle

dependencies {
    implementation('io.opentelemetry:opentelemetry-api:1.0.0')
    implementation('io.opentelemetry:opentelemetry-extension-annotations:1.0.0')
}

Adding attributes to the current span

A common need when instrumenting an application is to capture additional application-specific or
business-specific information as additional attributes to an existing span from the automatic
instrumentation. Grab the current span with Span.current() and use the setAttribute()
methods:

import io.opentelemetry.api.trace.Span;
// ...
Span span = Span.current();
span.setAttribute(..., ...);

Creating spans around methods with @WithSpan

Another common situation is to capture a span corresponding to one of your methods. The
@WithSpan annotation makes this straightforward:

import io.opentelemetry.extension.annotations.WithSpan;
public class MyClass {
  @WithSpan
  public void MyLogic() {
      <...>
  }
}

Each time the application invokes the annotated method, it creates a span that denote its duration
and provides any thrown exceptions. Unless specified as an argument to the annotation, the span name
will be <className>.<methodName>.

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.

Creating spans around methods with otel.instrumentation.methods.include

This is a way to to create a span around a first-party code method without using @WithSpan.

Creating spans manually with a Tracer

If @WithSpan doesn’t work for your specific use case, you’re still in luck!

The underlying OpenTelemetry API allows you to obtain a tracer
that can be used to manually create spans
and execute code within the scope of that span.

See the OpenTelemetry Java
QuickStart
for a detailed en example of how to configure OpenTelemetry with code and
how to use the Tracer, Scope and Span interfaces to
instrument your application.