> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Data with the OpenTelemetry Java Agent

> Instrument your Java application with the OpenTelemetry Java Agent and send traces, logs, and metrics to Honeycomb with minimal code changes.

export const FlexStyleTable = ({columns, overflowWrap = "normal", children}) => {
  const colWidths = columns ? columns.trim().split(/\s+/) : [];
  const scopeKey = [columns || "auto", overflowWrap].join("-").replace(/[^a-zA-Z0-9-]/g, "-");
  const colRules = colWidths.map((width, i) => `[data-fst="${scopeKey}"] table th:nth-of-type(${i + 1}) { width: ${width}; }`).join("\n");
  const css = `
    [data-fst="${scopeKey}"] table {
      table-layout: ${colWidths.length > 0 ? "fixed" : "auto"};
      width: 100%;
    }
    ${colRules}
    [data-fst="${scopeKey}"] table td { overflow-wrap: ${overflowWrap}; }
  `.trim();
  return <div className="flex-style-table" data-fst={scopeKey}>
      <style>{css}</style>
      {children}
    </div>;
};

export const HnyIcon = ({alias, path, size = 16, iconColor}) => {
  const iconMap = {
    "home": "house.svg",
    "marker": "caretFilledDown.svg",
    "show-marker-options": "chatTextLeft.svg",
    "download": "arrowLineDown.svg",
    "trace-waterfall": "trace.svg",
    "show-query-details": "listDashes.svg",
    "table": "table.svg",
    "log-lines": "logLines.svg",
    "chart": "chartLine.svg",
    "show-settings": "gear.svg",
    "add": "plus.svg",
    "remove": "delete.svg",
    "persist": "caretDown.svg",
    "close": "close.svg",
    "copy": "copy.svg",
    "zoom-in": "magnifyingGlassPlus.svg",
    "zoom-out": "magnifyingGlassMinus.svg",
    "color-assignment": "drop.svg",
    "drag": "dots-six-vertical.svg",
    "drawer": "drawer.svg",
    "show-actions": "dotsThree.svg",
    "edit": "pencil.svg",
    "delete": "trash.svg",
    "move": "arrowsOutCardinal.svg",
    "show-legend": "circleInfo.svg",
    "usage-ok": "usageGood.svg",
    "usage-warning": "usageWarning.svg",
    "usage-danger": "usageDanger.svg",
    "open-query-builder": "query.svg",
    "home-menu": "house.svg",
    "query-menu": "query.svg",
    "boards-menu": "board.svg",
    "triggers-menu": "bell.svg",
    "slos-menu": "handshake.svg",
    "service-map-menu": "serviceMap.svg",
    "history-menu": "clockCounterClockwise.svg",
    "manage-data-menu": "cube.svg",
    "usage-menu": "usageGood.svg",
    "show-details": "dotsThreeVertical.svg",
    "resize-handle": "board-panel-resize-handle.png",
    "standard-dataset": "cube.svg",
    "trace-dataset": "cubeChat.svg",
    "all-datasets": "linkedSquares.svg",
    "share": "arrowBentRight.svg",
    "run-in-query-builder": "arrowSquareUpRight.svg",
    "link": "link.svg",
    "text": "text.svg",
    "receive": "arrowLineDown.svg",
    "process": "lightning.svg",
    "sample": "drop.svg",
    "send": "arrowLineUp.svg",
    "submit": "arrowUp.svg",
    "canvas-menu": "sparkle.svg",
    "canvas": "sparkle.svg",
    "private": "lockKey.svg",
    "shared": "people.svg",
    "expand": "caretDown.svg",
    "previous": "caretLeft.svg",
    "next": "caretRight.svg"
  };
  const iconBasePath = "/_assets/icons/";
  const iconPath = path || (alias ? `${iconBasePath}${iconMap[alias]}` : undefined);
  return <span className="hny-icon" style={{
    display: "inline-block",
    width: `${size}px`,
    height: `${size}px`,
    maskImage: `url(${iconPath})`,
    maskSize: "contain",
    maskRepeat: "no-repeat",
    maskPosition: "center",
    WebkitMaskImage: `url(${iconPath})`,
    WebkitMaskSize: "contain",
    WebkitMaskRepeat: "no-repeat",
    WebkitMaskPosition: "center",
    backgroundColor: iconColor || "var(--hny-icon-color)",
    verticalAlign: "middle"
  }} />;
};

export const CalloutLearn = ({children}) => {
  return <Callout icon="brain-circuit" color="#8B5CF6">
      {children}
    </Callout>;
};

Use the OpenTelemetry Java Agent to instrument Java applications in a standard, vendor-agnostic, and future-proof way and send telemetry data to Honeycomb.

In this guide, we will walk you through instrumenting with OpenTelemetry Java Agent, which will include adding automatic instrumentation to your application.

<CalloutLearn>
  For more structured learning, check out the [Instrumentation for OpenTelemetry Java](https://academy.honeycomb.io/app/courses/406eb56b-a3ea-4d48-8ad3-3e2c1945c143) course from Honeycomb Academy.
</CalloutLearn>

## Before You Begin

Before you can set up automatic instrumentation for your Java application, you will need to do a few things.

### Prepare Your Development Environment

To complete the required steps, you will need:

* A working Java environment
* An application written in Java

### Get Your Honeycomb API Key

To send data to Honeycomb, you'll need to [sign up for a free Honeycomb account](https://ui.honeycomb.io/signup) and [create a Honeycomb Ingest API Key](/configure/environments/manage-api-keys/#create-api-key).
To get started, you can create a key that you expect to swap out when you deploy to production.
Name it something helpful, perhaps noting that it's a getting started key.
Make note of your API key; for security reasons, you will not be able to see the key again, and you will need it later!

<Tip>
  For setup, make sure you check the "Can create datasets" checkbox so that your data will show up in Honeycomb. Later, when you replace this key with a permanent one, you can uncheck that box.
</Tip>

If you want to use an API key you previously stored in a secure location, you can also [look up details for Honeycomb API Keys](/configure/environments/manage-api-keys/#find-api-keys) any time in your Environment Settings, and use them to retrieve keys from your storage location.

## Add Automatic Instrumentation

Automatic instrumentation is handled with a Java Agent that runs alongside your application.
Adding manual instrumentation uses the OpenTelemetry API, which is available when using our SDK as a dependency.

### Acquire Dependencies

The OpenTelemetry Java Agent supports many [Java libraries and frameworks](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries---frameworks).

The automatic instrumentation agent for OpenTelemetry Java will automatically generate trace data from your application.
The agent is packaged as a JAR file and is run alongside your app.

In order to use the automatic instrumentation agent, you must first download it:

```shell theme={}
curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
```

### Configure

Create an `otelconfig.yaml` file with the following content:

```yaml theme={}
file_format: "1.0"

resource:
  attributes:
    - name: service.name
      value: ${OTEL_SERVICE_NAME:-my-service}

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: https://api.honeycomb.io
            headers:
              - name: x-honeycomb-team
                value: ${HONEYCOMB_API_KEY}

meter_provider: # (*)
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: https://api.honeycomb.io
            headers:
              - name: x-honeycomb-team
                value: ${HONEYCOMB_API_KEY}
              - name: x-honeycomb-dataset
                value: ${HONEYCOMB_METRICS_DATASET}

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: https://api.honeycomb.io
            headers:
              - name: x-honeycomb-team
                value: ${HONEYCOMB_API_KEY}

propagator:
  composite:
    - tracecontext:
    - baggage:
```

Fields marked with an asterisk (\*) are required for exporting metrics to Honeycomb.

Set the following environment variables before running your application:

| Environment Variable        | Value                                         |
| :-------------------------- | :-------------------------------------------- |
| `HONEYCOMB_API_KEY`         | Your Honeycomb API key                        |
| `OTEL_SERVICE_NAME`         | The name of your service                      |
| `HONEYCOMB_METRICS_DATASET` | The Honeycomb dataset to send metrics to (\*) |

<Note>
  If you are using the EU instance, replace `https://api.honeycomb.io` with `https://api.eu1.honeycomb.io` in the configuration file.
</Note>

You can also configure the SDK using [environment variables or system properties](https://github.com/open-telemetry/opentelemetry-java/tree/main/sdk-extensions/autoconfigure).

<Note>
  If you use [Honeycomb Classic](/troubleshoot/product-lifecycle/recommended-migrations/#migrate-from-honeycomb-classic-to-honeycomb-environments), you must also specify the Dataset for traces using the `x-honeycomb-dataset` header:

  ```yaml theme={}
  headers:
    - name: x-honeycomb-team
      value: ${HONEYCOMB_API_KEY}
    - name: x-honeycomb-dataset
      value: your-dataset
  ```
</Note>

### Run

Point the agent at your configuration file using the `OTEL_CONFIG_FILE` environment variable, then run your application:

```shell theme={}
OTEL_CONFIG_FILE=./otelconfig.yaml java -javaagent:opentelemetry-javaagent.jar -jar /path/to/myapp.jar
```

In Honeycomb's UI, you should now see your application's incoming requests and outgoing HTTP calls generate traces.

## Add Custom Instrumentation

Automatic instrumentation is the easiest way to get started with instrumenting your code.
To get additional insight into your system, you should also add custom, or manual, instrumentation where appropriate.
You can use manual instrumentation whether you are using the Agent or the Builder.
Follow the instructions below to add custom instrumentation to your code.

To learn more about custom, or manual, instrumentation, visit the comprehensive set of topics covered by [Manual Instrumentation for Java](https://opentelemetry.io/docs/languages/java/manual/), including [the Annotations API](https://opentelemetry.io/docs/languages/java/automatic/annotations/), in OpenTelemetry's documentation.

### Acquire Dependencies

To add custom instrumentation, some OpenTelemetry libraries can be added as dependencies for your application.
The OpenTelemetry API provides methods that let you access the currently executing span and add attributes to it, and/or to create new spans.
The Annotations library provides decorators the OpenTelemetry JavaAgent will use to [create spans for decorated methods](#creating-spans-around-methods).

<Note>
  Use the `opentelemetry-instrumentation-bom` to align the versions of these dependencies with the version of OpenTelemetry JavaAgent in use.
</Note>

<Tabs>
  <Tab title="Gradle">
    ```groovy theme={}
    dependencies {
      // Replace '{opentelemetry_java_instrumentation.version}' below with the version of the OTel JavaAgent in use.
      implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom:{opentelemetry_java_instrumentation.version}"))
      implementation("io.opentelemetry:opentelemetry-api")
      implementation("io.opentelemetry.instrumentation:opentelemetry-instrumentation-annotations")
    }
    ```
  </Tab>

  <Tab title="Maven">
    ```xml theme={}
    <project>
        <dependencyManagement>
            <dependencies>
                <dependency>
                    <groupId>io.opentelemetry.instrumentation</groupId>
                    <artifactId>opentelemetry-instrumentation-bom</artifactId>
                    <!-- Replace '{opentelemetry_java_instrumentation.version}' below with the version of the OTel JavaAgent in use -->
                    <version>{opentelemetry_java_instrumentation.version}</version>
                    <type>pom</type>
                    <scope>import</scope>
                </dependency>
            </dependencies>
        </dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>io.opentelemetry</groupId>
                <artifactId>opentelemetry-api</artifactId>
            </dependency>
            <dependency>
                <groupId>io.opentelemetry.instrumentation</groupId>
                <artifactId>opentelemetry-instrumentation-annotations</artifactId>
            </dependency>
        </dependencies>
    </project>
    ```
  </Tab>
</Tabs>

### Add Attributes to Spans

Adding attributes to a currently executing span in a trace can be useful.
For example, you may have an application or service that handles users and you want to associate the user with the span when querying your service in Honeycomb.
To do this, get the current span from the context and set an attribute with the user ID.

In your code, import `io.opentelemetry.api.trace.Span` to get access to the span:

```java theme={}
import io.opentelemetry.api.trace.Span;

...

Span span = Span.current();
span.setAttribute("user.id", user.getId());
```

This will add a `user.id` field to the current span so that you can use the field in `WHERE`, `GROUP BY` or `ORDER` clauses in the Honeycomb query builder.

### Acquire a Tracer

To create spans, you need to get a `Tracer`.

```java theme={}
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Tracer;

//...

Tracer tracer = GlobalOpenTelemetry.getTracer("tracer.name.here");
```

When you create a `Tracer`, OpenTelemetry requires you to give it a name as a string.
This string is the only required parameter.

When traces are sent to Honeycomb, the name of the `Tracer` is turned into the `library.name` field, which can be used to show all spans created from a particular tracer.

In general, pick a name that matches the appropriate scope for your traces.
If you have one tracer for each service, then use the service name.
If you have multiple tracers that live in different "layers" of your application, then use the name that corresponds to that "layer".

The `library.name` field is also used with traces created from instrumentation libraries.

### Create New Spans

Automatic instrumentation can show the shape of requests to your system, but only you know the really important parts.
To get the full picture of what's happening, you will have to add custom, or manual, instrumentation and create some custom spans.
To do this, create or re-use `Tracer` registered by the Agent and start a span.

In your code, import `io.opentelemetry.api.GlobalOpenTelemetry`, `io.opentelemetry.api.trace.Span`, and `io.opentelemetry.api.trace.Tracer`:

```java theme={}
import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;

...

Tracer tracer = GlobalOpenTelemetry.getTracer("my-service");
Span span = tracer.spanBuilder("expensive-query").startSpan();

// ... do cool stuff

span.end();
```

#### Creating Spans Around Methods

You can also use the annotation `@WithSpan` to wrap the execution of a method with a span.
The span will be automatically closed once the method has completed.
Unless explicitly specified, the span will be named `className.methodName`.
To override the name of the span, add a name in parentheses as an argument.

In your code, import `io.opentelemetry.instrumentation.annotations.WithSpan` to allow usage of this annotation:

```java theme={}
import io.opentelemetry.instrumentation.annotations.WithSpan;

...

@WithSpan("importantSpan")
public String getImportantInfo() {
    return importantInfo;
}
```

### Add Multi-Span Attributes

Sometimes you want to add the same attribute to many spans within the same trace.
This attribute may include variables calculated during your program, or other useful values for correlation or debugging purposes.

To add this attribute, leverage the OpenTelemetry concept of [baggage](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/overview.md#baggage-signal).
Baggage allows you to add a `key` with a `value` as an attribute to every subsequent child span of the current application context.

In your code, import `io.opentelemetry.api.baggage.Baggage` to allow use of the `Baggage` class:

```java theme={}
import io.opentelemetry.api.baggage.Baggage;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.context.Scope;

...

try (final Scope ignored = Baggage.current()
    .toBuilder()
    .put("app.username", name)
    .build()
    .makeCurrent()
) {
    // all subsequently created spans in this block will have the `app.username` attribute
}
```

<Note>
  Any Baggage attributes that you set in your application will be attached to outgoing network requests as a header. If your service communicates to a third party API, do **NOT** put sensitive information in the Baggage attributes.
</Note>

## Sampling

You can configure the OpenTelemetry SDK to [sample the data](/manage-data-volume/sample/guidelines/) it generates.
Honeycomb [weights sampled data based on sample rate](/manage-data-volume/sample/sampled-data-in-honeycomb/), so you must set a resource attribute containing the sample rate.

Use a [`TraceIdRatioBased` sampler](https://opentelemetry.io//docs/specs/otel/trace/sdk/#traceidratiobased), with a ratio expressed as `1/N`.
Then, also create a resource attribute called `SampleRate` with the value of `N`.
This allows Honeycomb to reweigh scalar values, like counts, so that they are accurate even with sampled data.

In the example below, our goal is to keep approximately half (1/2) of the data volume.
The resource attribute contains the denominator (2), while the OpenTelemetry sampler argument contains the decimal value (0.5).

| System Property /<br /> Environment Variable                | Value          |
| :---------------------------------------------------------- | :------------- |
| `otel.traces.sampler` <br />`OTEL_TRACES_SAMPLER`           | `traceidratio` |
| `otel.traces.sampler.arg` <br />`OTEL_TRACES_SAMPLER_ARG`   | `0.5`          |
| `otel.resource.attributes` <br />`OTEL_RESOURCE_ATTRIBUTES` | `SampleRate=2` |

The value of `SampleRate` **must** be a positive integer.

## Using HTTP Instead of gRPC

By default, OpenTelemetry for Java uses gRPC protocol.
To use HTTP instead of gRPC, update the protocol using one of the configuration methods:

* System property: `-Dotel.exporter.otlp.protocol=http/protobuf`
* Environment variable: `export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`

The protocol can also be set specific to each signal, such as `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` and `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`.

<Note>
  If you are sending data to Honeycomb directly, you can find Trace and Metric Endpoint configuration options, as well as OpenTelemetry Headers, in the OpenTelemetry for Java chart.

  If you are using an [OpenTelemetry Collector](/send-data/opentelemetry/collector/), specify the endpoint of the collector, and add the headers to the collector configuration file.
</Note>

## Endpoint URLs for OTLP/HTTP

When using the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable with an SDK and an HTTP exporter, the final path of the endpoint is modified by the SDK to represent the specific signal being sent.

For example, when exporting trace data, the endpoint is updated to append `v1/traces`.
When exporting metrics data, the endpoint is updated to append `v1/metrics`.
So, if you were to set the `OTEL_EXPORTER_OTLP_ENDPOINT` to `https://api.honeycomb.io`, traces would be sent to `https://api.honeycomb.io/v1/traces` and metrics would be sent to `https://api.honeycomb.io/v1/metrics`.

The same modification is not necessary for gRPC.

```shell theme={}
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io # US instance
#export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.eu1.honeycomb.io # EU instance
```

If the desired outcome is to send data to a different endpoint depending on the signal, use `OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT` instead of the more generic `OTEL_EXPORTER_OTLP_ENDPOINT`.

When using a signal-specific environment variable, these paths must be appended manually.
Set `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` for traces, appending the endpoint with `v1/traces`, and `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` for metrics, appending the endpoint with `v1/metrics`.

Send both traces and metrics to Honeycomb using this method by setting the following variables:

```shell theme={}
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.honeycomb.io/v1/traces # US instance
#export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.eu1.honeycomb.io/v1/traces # EU instance

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.honeycomb.io/v1/metrics # US instance
#export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.eu1.honeycomb.io/v1/metrics # EU instance
```

More details about endpoints and signals can be found in the [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md).

## Troubleshooting

To explore common issues when sending data, visit [Common Issues with Sending Data in Honeycomb](/troubleshoot/common-issues/sending-data/#opentelemetry-sdks-and-honeycomb-distributions).