OpenTelemetry for Java | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

OpenTelemetry for Java

Honeycomb has a OpenTelemetry Distribution for Java that makes it easy to add automatic and manual instrumentation to your applications and have trace data sent to Honeycomb. Automatic instrumentation is handled with a Java Agent that runs alongside your application. Manual instrumentation can be added using the OpenTelemetry API.

The Automatic Instrumentation agent supports an impressive number of Java libraries and frameworks.

Requirements  🔗

These instructions will explain how to set up automatic and manual instrumentation for a service written in Java. In order to follow along, you will need:

  • Java version 8 or newer.
  • An application written in Java.
  • A Honeycomb API Key. You can find your API key on your Team Settings page. If you don’t have an API key yet, sign up for a free Honeycomb account.

Automatic Instrumentation with the OpenTelemetry Java Agent  🔗

The auto-instrumentation agent for Honeycomb OpenTelemetry Java will automatically generate trace data from your application. The agent is packaged as a JAR file and is specified as a command-line argument when invoking the Java Virtual Machine (JVM).

In order to use the auto-instrumentation agent, you must first download and distribute the JAR file.

The agent JAR file must be available when running the java process that starts your service. The file can be downloaded from the GitHub Releases page or you can download it with a CLI tool like curl:

curl -LO https://github.com/honeycombio/honeycomb-opentelemetry-java/releases/download/v0.4.0/honeycomb-opentelemetry-javaagent-0.4.0-all.jar

Once the JAR file is downloaded, you can configure the agent with Honeycomb credentials.

Configuration  🔗

The Honeycomb Agent has the following configuration options, which can be specified as system properties or environment variables. System properties take precedence over environment variables if both are specified.

System Property Environment Variable Description
honeycomb.api.key HONEYCOMB_API_KEY [required] Your Honeycomb API key
honeycomb.dataset HONEYCOMB_DATASET [required] Honeycomb dataset where traces will be sent
honeycomb.api.endpoint HONEYCOMB_API_ENDPOINT [optional] Honeycomb ingest endpoint (defaults to https://api.honeycomb.io:443).
sample.rate SAMPLE_RATE [optional] Sample rate for the deterministic sampler (defaults to 1, always sample)
service.name SERVICE_NAME [optional] service.name attribute to be used for all spans (defaults to empty)

These configuration options are specified when invoking the JVM. The following examples assume that the JAR file is in the current working directory. Configure the auto-instrumentation agent using environment variables:

SAMPLE_RATE=2 \
SERVICE_NAME=my-favorite-service \
HONEYCOMB_API_KEY=my-api-key \
HONEYCOMB_DATASET=my-dataset \
java -javaagent:honeycomb-opentelemetry-javaagent-0.4.0-all.jar -jar /path/to/myapp.jar

Or, configure using system properties:

java \
-Dsample.rate=2 \
-Dservice.name=my-favorite-service \
-Dhoneycomb.api.key=my-api-key \
-Dhoneycomb.dataset=my-dataset \
-javaagent:honeycomb-opentelemetry-javaagent-0.4.0-all.jar -jar /path/to/myapp.jar

Adding Manual Instrumentation  🔗

Auto-instrumentation is the easiest way to get started with instrumenting your code, but in order to get the most insight into your system, you should add manual instrumentation where appropriate. To do this, use the Honeycomb OpenTelemetry SDK to access the currently executing span and add attributes to it, and/or to create new spans.

To add manual instrumentation, import the Honeycomb OpenTelemetry SDK as a dependency in your project.

dependencies {
  compile('io.honeycomb:honeycomb-opentelemetry-sdk:0.4.0')
}
<dependency>
  <groupId>io.honeycomb</groupId>
  <artifactId>honeycomb-opentelemetry-sdk</artifactId>
  <version>0.4.0</version>
</dependency>

Adding Context to Spans  🔗

It’s often beneficial to add context to a currently executing span in a trace. 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 dataset in Honeycomb. In order to do this, get the current span from the context and set an attribute with the user ID:

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.

Creating New Spans  🔗

Auto-instrumentation can show the shape of requests to your system, but only you know the really important parts. In order to get the full picture of what’s happening, you will have to add manual instrumentation and create some custom spans. To do this, grab the tracer registered by the agent:

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.

import io.opentelemetry.extension.annotations.WithSpan;

...

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

Using the Honeycomb SDK Builder  🔗

If you do not wish to use the auto-instrumentation agent, or wish to do more advanced instrumentation like adding custom span processors, you can use the Honeycomb SDK to instantiate an HoneycombSdk instance, which provides access to a tracer and the rest of the OpenTelemetry API. The HoneycombSdk builder provides convenient methods for configuration:

import io.honeycomb.opentelemetry.HoneycombSdk;
import io.honeycomb.opentelemetry.sdk.trace.samplers.DeterministicTraceSampler;

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.Tracer;

HoneycombSdk honeycomb = new HoneycombSdk.Builder()
    .setApiKey("your-api-key")
    .setDataset("your dataset")
    .setSampler(new DeterministicTraceSampler(2)) // optional
    .setServiceName("example-service")            // optional
    .build();

Tracer tracer = honeycomb.getTracer("my-service");
Span span = tracer.spanBuilder("some-operation").startSpan();
span.setAttribute("message", "Hello, World");
span.end();

Multi-span Attributes  🔗

It can be valuable to add an attribute that is available on every span within the same trace. Using our BaggageSpanProcessor, you can add “baggage” to your spans. Baggage is simply a list of key-value pairs to be added to all subsequent spans within the trace. This can include variables calculated during your program, or other useful values for correlation or debugging purposes.

import io.opentelemetry.api.baggage.Baggage;
import io.opentelemetry.api.trace.Span;

...

Span.current().setAttribute("app.username", name);
Baggage.current()
  .toBuilder()
  .put("app.username", name)
  .build()
  .makeCurrent();

Sampling  🔗

Deterministic head sampling can be done with both the agent and manual instrumentation. To add sampling to the agent, specify the SAMPLE_RATE environment variable or the -Dsample.rate system property when invoking the JVM. The agent will read these variables and expect an integer that represents the sample rate you would like to apply. For example, a value of 5 means that one out of every five traces will be sent to Honeycomb. When using manual instrumentation and the Honeycomb SDK builder, specify a deterministic sampler with a sample rate as an argument to the constructor:

HoneycombSdk honeycomb = HoneycombSdk.Builder()
    .setApiKey("your-api-key")
    .setDataset("your dataset")
    .setSampler(new DeterministicSampler(5)) // send 1/5 traces
    .build();

The setSampler method accepts any instance of a class that implements the io.opentelemetry.sdk.trace.samplers.Sampler interface. Look at the provided deterministic sampler as an example of how to create your own custom sampler, if needed.

Distributed Trace Propagation  🔗

When a service calls another service, you want to be sure that the relevant trace information is propagated from one service to the other. This allows Honeycomb to connect the two services in a trace. Trace context propagation is done by sending and parsing headers that conform to the W3C Trace Context specification. When using the auto-instrumentation agent, this will be done automatically: headers will be included in calls made from supported HTTP or gRPC clients and parsed by supported web frameworks.

In order for this to work, both the sending and receiving service must be using the same propagation format, and both services must be configured to send data to the same Honeycomb dataset.