Send Data with the OpenTelemetry Agent for Java | Honeycomb

Send Data with the OpenTelemetry Agent for Java

Use the OpenTelemetry Agent for Java 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 Agent for Java, which will include adding automatic instrumentation to your application.

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 and create a Honeycomb Ingest 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.

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 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.

Configure 

As per the OpenTelemetry specification, you must set a service.name resource in your SDK configuration. The service name is used as the name of a dataset to store trace data in Honeycomb.

When using OpenTelemetry for Java, all of the following configuration properties are required:

System Property /
Environment Variable
Value
otel.traces.exporter
OTEL_TRACES_EXPORTER
otlp
otel.metrics.exporter
OTEL_METRICS_EXPORTER
otlp (*)
otel.exporter.otlp.endpoint
OTEL_EXPORTER_OTLP_ENDPOINT
https://api.honeycomb.io (US instance)
https://api.eu1.honeycomb.io (EU instance)
otel.exporter.otlp.traces.endpoint
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
https://api.honeycomb.io/v1/traces (defaults to value of OTEL_EXPORTER_OTLP_ENDPOINT)
otel.exporter.otlp.metrics.endpoint
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
https://api.honeycomb.io/v1/metrics (US instance)
https://api.eu1.honeycomb.io/v1/metrics (EU instance)(*)
otel.exporter.otlp.headers
OTEL_EXPORTER_OTLP_HEADERS
x-honeycomb-team=HONEYCOMB_API_KEY
otel.exporter.otlp.traces.headers
OTEL_EXPORTER_OTLP_TRACES_HEADERS
x-honeycomb-team=HONEYCOMB_API_KEY (defaults to value of OTEL_EXPORTER_OTLP_HEADERS)
otel.exporter.otlp.metrics.headers
OTEL_EXPORTER_OTLP_METRICS_HEADERS
x-honeycomb-team=HONEYCOMB_API_KEY,x-honeycomb-dataset=HONEYCOMB_DATASET (*)
otel.service.name
OTEL_SERVICE_NAME
service.name attribute to be used for all spans

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

If you do not have a service name set in TracerProvider configuration code, you must also set the OTEL_SERVICE_NAME environment variable.

To learn more about configuration options, visit the OpenTelemetry SDK Autoconfigure GitHub repository.

If desired, you can use a configuration file to store environment variables or system properties for the Java Agent. You must provide a path to the configuration file using either a system property of otel.javaagent.configuration-file or an environment variable of OTEL_JAVAAGENT_CONFIGURATION_FILE.

For example, to specify a configuration file using system properties to run the agent with an application:

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.javaagent.configuration-file=path/to/config-file \
     -jar myapp.jar

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, specify the endpoint of the collector, and add the headers to the collector configuration file.

Sampling 

You can configure the OpenTelemetry SDK to sample the data it generates. Honeycomb weights sampled data based on sample rate, so you must set a resource attribute containing the sample rate.

Use a TraceIdRatioBased sampler, 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 /
Environment Variable
Value
otel.traces.sampler
OTEL_TRACES_SAMPLER
traceidratio
otel.traces.sampler.arg
OTEL_TRACES_SAMPLER_ARG
0.5
otel.resource.attributes
OTEL_RESOURCE_ATTRIBUTES
SampleRate=2

The value of SampleRate must be a positive integer.

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.

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:

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.

Troubleshooting 

To explore common issues when sending data, visit Common Issues with Sending Data in Honeycomb.