# Extending instrumentations with the API

> Use the OpenTelemetry API in combination with the Java agent to extend the automatically generated telemetry with custom spans and metrics

---

LLMS index: [llms.txt](/llms.txt)

---

## Introduction

In addition to the out-of-the-box instrumentation, you can extend the Java agent
with custom manual instrumentation using the OpenTelemetry API. This allows you
to create [spans](/docs/concepts/signals/traces/#spans) and
[metrics](/docs/concepts/signals/metrics) for your own code without doing too
many code changes.

## Dependencies

Add a dependency on the `opentelemetry-api` library.

### Maven

```xml
<dependencies>
  <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
    <version>1.55.0</version>
  </dependency>
</dependencies>
```

### Gradle

```groovy
dependencies {
    implementation('io.opentelemetry:opentelemetry-api:1.55.0')
}
```

## OpenTelemetry

The Java agent is a special case where `GlobalOpenTelemetry` is set by the
agent. Simply call `GlobalOpenTelemetry.getOrNoop()` to access the
`OpenTelemetry` instance.

## Span

> [!NOTE]
>
> For the most common use cases, use the `@WithSpan` annotation instead of
> manual instrumentation. See [Annotations](../annotations) for more
> information.

```java
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Tracer;

Tracer tracer = GlobalOpenTelemetry.getTracer("application");
```

Use the `Tracer` to create a span as explained in the
[Span](/docs/languages/java/api/#span) section.

A full example can be found in the [example repository][].

## Meter

```java
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.metrics.Meter;

Meter meter = GlobalOpenTelemetry.getMeter("application");
```

Use the `Meter` to create a counter, gauge or histogram as explained in the
[Meter](/docs/languages/java/api/#meter) section.

A full example can be found in the [example repository][].

[example repository]:
  https://github.com/open-telemetry/opentelemetry-java-examples/tree/main/javaagent