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 an 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. Additional manual instrumentation can be added using the OpenTelemetry API, which is available when using our SDK as a dependency.

The OpenTelemetry Java Agent supports many Java libraries and frameworks.

If you do not want to use automatic instrumentation, you will need to use the SDK Builder to instantiate an OpenTelemetryConfiguration instance. The Builder is not needed if the Agent is being used.

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.6.1/honeycomb-opentelemetry-javaagent-0.6.1-all.jar

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

Configuration  🔗

At a minimum, you need to configure the Honeycomb Agent with your API key and datasets.

Configure it using environment variables:

SERVICE_NAME=my-favorite-service \
HONEYCOMB_API_KEY=my-api-key \
HONEYCOMB_TRACES_DATASET=my-traces \
HONEYCOMB_METRICS_DATASET=my-metrics \
java -javaagent:honeycomb-opentelemetry-javaagent-0.6.1-all.jar -jar /path/to/myapp.jar

Or, configure it using system properties:

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

Advanced Configuration  🔗

This is the complete list of configuration options for the Honeycomb Agent. It can be configured using system properties or environment variables. System properties take precedence over environment variables if both are specified.

System Property /
Environment Variable
Default Value Description
honeycomb.api.key
HONEYCOMB_API_KEY
None [required – see note below] Your Honeycomb API key
honeycomb.traces.apikey
HONEYCOMB_TRACES_APIKEY
Value of honeycomb.api.key Your Honeycomb API key for sending traces
honeycomb.metrics.apikey
HONEYCOMB_METRICS_APIKEY
Value of honeycomb.api.key Your Honeycomb API key for sending metrics
honeycomb.dataset
HONEYCOMB_DATASET
None [required – see note below] Honeycomb dataset where traces will be sent
honeycomb.traces.dataset
HONEYCOMB_TRACES_DATASET
Value of honeycomb.dataset Honeycomb dataset where traces will be sent
honeycomb.metrics.dataset
HONEYCOMB_METRICS_DATASET
None Honeycomb dataset where traces will be sent (metrics will not be exported if this is not configured)
honeycomb.api.endpoint
HONEYCOMB_API_ENDPOINT
https://api.honeycomb.io:443 Honeycomb ingest endpoint.
honeycomb.traces.endpoint
HONEYCOMB_TRACES_ENDPOINT
Value of honeycomb.api.endpoint Honeycomb ingest endpoint for traces (defaults to the value of HONEYCOMB_API_ENDPOINT).
honeycomb.metrics.endpoint
HONEYCOMB_METRICS_ENDPOINT
Value of honeycomb.api.endpoint Honeycomb ingest endpoint for metrics (defaults to the value of HONEYCOMB_API_ENDPOINT).
sample.rate
SAMPLE_RATE
1 (retain all data) Sample rate for the deterministic sampler
service.name
SERVICE_NAME
None service.name attribute to be used for all spans

API key and dataset configuration options are required if you’re sending data to Honeycomb directly. If you’re using an OpenTelemetry Collector, you would specify your API key and dataset in the collector configuration file instead.

Adding Manual Instrumentation  🔗

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

To add manual instrumentation, add the Honeycomb OpenTelemetry SDK as a dependency in your project. This provides access to the OpenTelemetry APIs, which lets you access the currently executing span and add attributes to it, and/or to create new spans.

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

Adding Context to Spans Using Attributes  🔗

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.

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

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, select the Tracer registered by the Agent and build a span.

In your code, import io.opentelemetry.api.OpenTelemetry, io.opentelemetry.api.trace.Span, and io.opentelemetry.api.trace.Tracer.

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

...

Tracer tracer = OpenTelemetry.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.extension.annotations.WithSpan to allow usage of this annotation.

import io.opentelemetry.extension.annotations.WithSpan;

...

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

Multi-span Attributes  🔗

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

We’ll leverage the OpenTelemetry concept of baggage to do this. 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.

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

...

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

Sampling  🔗

Deterministic head sampling can be used with the Java Agent, with or without manual instrumentation.

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.

To add sampling to the agent, specify the SAMPLE_RATE environment variable or the -Dsample.rate system property when invoking the Java Virtual Machine (JVM), as shown in Advanced Configuration.

Metrics Collection  🔗

Honeycomb Enterprise accounts can also send metrics to Honeycomb.

JVM emits metrics at regular intervals that can be sent automatically to a Honeycomb dataset. These metrics will show up in data as runtime.jvm.gc.count, runtime.jvm.gc.time, runtime.jvm.memory.area, and so on.

Metrics are disabled by default. To enable metrics, set a HONEYCOMB_METRICS_DATASET environment variable. Optionally, set a specific HONEYCOMB_METRICS_APIKEY or HONEYCOMB_METRICS_ENDPOINT (if different from the traces API key and endpoint), as shown in Advanced Configuration.

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.

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. The W3C Trace Context format is used in both automatic and manual instrumentation. If you’ve configured your traces to use something else, you’ll need to switch to the W3C format.

Using the Honeycomb SDK Builder  🔗

If you do not wish to use the auto-instrumentation agent, and/or wish to do more advanced instrumentation like adding other span processors or extensions, you can use the Honeycomb SDK to instantiate an OpenTelemetryConfiguration instance, which provides access to a Tracer and the rest of the OpenTelemetry API.

This should be configured as early as possible in the entry point of your application. Keep in mind, this builder is not required if the agent is in use.

Aside from requiring this builder, setting up manual instrumentation will be the same as when using the agent.

The OpenTelemetryConfiguration builder provides convenient methods for configuration:

import io.honeycomb.opentelemetry.OpenTelemetryConfiguration;
import io.honeycomb.opentelemetry.sdk.trace.samplers.DeterministicTraceSampler; // optional
import io.honeycomb.opentelemetry.sdk.trace.spanprocessors.BaggageSpanProcessor; // optional

public OpenTelemetry honeycomb() {
  return OpenTelemetryConfiguration.builder()
    .setApiKey("your-api-key")
    .setDataset("your dataset")
    .setSampler(new DeterministicTraceSampler(2)) // optional - sends 1/2 of all traces generated
    .setServiceName("example-service")            // optional
    .addSpanProcessor(new BaggageSpanProcessor()) // optional
    .buildAndRegisterGlobal();
}

When using the Honeycomb SDK builder, specify a span processor and/or a sampler with a sample rate as an argument to the constructor.

The BaggageSpanProcessor is available as part of the Honeycomb SDK; it is what allows for multi-span attributes. The DeterministicTraceSampler is available as part of the Honeycomb SDK that samples based on a common field, given a sample rate.

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.

Troubleshooting  🔗

Debug Mode  🔗

To enable debugging when running with the OpenTelemetry Java Agent, set the otel.javaagent.debug system property or OTEL_JAVAAGENT_DEBUG environment variable to true. When this setting is provided, the Agent configures a LoggingSpanExporter that logs traces & metrics data.

gRPC transport customization  🔗

A gRPC transport is required to transmit OpenTelemetry data. HoneycombSDK includes grpc-netty-shaded.

If you’re using another gRPC dependency, version conflicts can come up with an error like this:

java.lang.NoSuchMethodError: io/grpc/ClientStreamTracer$StreamInfo$Builder.setPreviousAttempts(I)Lio/grpc/ClientStreamTracer$StreamInfo$Builder; (loaded from file:/app.jar by jdk.internal.loader.ClassLoaders$AppClassLoader@193b9e51) called from class io.grpc.internal.GrpcUtil (loaded from file:/io.grpc/grpc-core/1.41.0/882b6572f7d805b9b32e3993b1d7d3e022791b3a/grpc-core-1.41.0.jar by jdk.internal.loader.ClassLoaders$AppClassLoader@193b9e51).

If you’d like to use another gRPC transport, you can exclude the grpc-netty-shaded transitive dependency:

dependencies {
    implementation('io.honeycomb:honeycomb-opentelemetry-sdk:0.5.0') {
        exclude group: 'io.grpc', module: 'grpc-netty-shaded'
    }
}
<project>
    <dependencies>
        <dependency>
            <groupId>io.honeycomb</groupId>
            <artifactId>honeycomb-opentelemetry-sdk</artifactId>
            <version>0.5.0</version>
            <exclusions>
                <exclusion>
                    <groupId>io.grpc</groupId>
                    <artifactId>grpc-netty-shaded</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>
</project>