OpenTelemetry | Honeycomb

Honeycomb.io Documentation
  1. Docs
  2. Send Data to Honeycomb
  3. OpenTelemetry

OpenTelemetry

Honeycomb supports OpenTelemetry. OpenTelemetry is an open-source framework for collecting and managing telemetry data from distributed systems. It provides a standardized way of instrumenting code to generate telemetry data, such as traces, metrics, and logs, and exporting that data to various backends for analysis and visualization. OpenTelemetry supports multiple programming languages and platforms, making it easy to integrate with a variety of systems.

OpenTelemetry comprises two main components: instrumentation libraries and exporters. The instrumentation libraries enable developers to collect telemetry data from their applications, while the exporters allow users to send the data to backends like Honeycomb.

If instrumenting code for the first time, you can use one of Honeycomb’s OpenTelemetry Distributions.

If your application is already instrumented with OpenTelemetry, you can send OpenTelemetry Protocol (OTLP) data directly to Honeycomb. To learn more, read “Instrumenting with OpenTelemetry”.

Honeycomb supports receiving telemetry data via OpenTelemetry’s native protocol, OTLP, over gRPC, HTTP/protobuf, and HTTP/JSON. The minimum supported versions of OTLP protobuf definitions are 0.7.0 for traces and metrics.

If a system is already instrumented with legacy instrumentation like OpenTracing, OpenCensus, Zipkin, or Jaeger, you should use an OpenTelemetry Collector to convert into OTLP and export your data to Honeycomb.

Instrumenting with Honeycomb OpenTelemetry Distributions 

Honeycomb’s OpenTelemetry Distributions wrap an OpenTelemetry SDK and provide more features in addition to what the SDK already gives you:

  • Configuration defaults that make sending data to Honeycomb as easy as possible
  • Additional configuration options for non-default scenarios
  • Full compatibility with existing OpenTelemetry instrumentation libraries or API usage
  • Deterministic sampling for spans, configurable to your preferred sampling rate. (Defaults to a sample rate of 1.0)
  • Multi-span attributes via Baggage. This gives you automatic propagation of span attributes, so you can add attributes to a span and have it propagate down to all child spans

We currently support distributions for Go, Java, .NET, Node.js, and Python.

OpenTelemetry Distro for Go
Instrument your Go App with our OpenTelemetry Distro.
OpenTelemetry Distro for Java
Instrument your Java App with our OpenTelemetry Distro.
OpenTelemetry Distro for .NET
Instrument your .Net App with our OpenTelemetry Distro.
OpenTelemetry Distro for Node.js
Instrument your Node.js App with our OpenTelemetry Distro.
OpenTelemetry Distro for Python
Instrument your Python App with our OpenTelemetry Distro.

Instrumenting with OpenTelemetry 

We also have OpenTelemetry documentation for some languages that do not have a Honeycomb SDK distribution yet. Select your application’s language for instructions on instrumenting with OpenTelemetry:

OpenTelemetry for Ruby
Instrument your Ruby App with OpenTelemetry.

Using the Honeycomb OpenTelemetry Endpoint 

If your language is not listed above, you can send data to Honeycomb directly over OTLP with an OpenTelemetry SDK or the OpenTelemetry Collector.

Tip
For Rust, we recommend that you use the opentelemetry and opentelemetry-otlp crates to send data over OTLP to Honeycomb. Follow the instructions below for the required configuration values.

An OpenTelemetry integration should set the endpoint and headers.

Set the endpoint:

  • For OTLP/gRPC, export OTEL_EXPORTER_OTLP_ENDPOINT=api.honeycomb.io:443
  • For OTLP/HTTPS, export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io/

Set your API key:

export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key"

Set the service name in the OTEL_SERVICE_NAME environment variable.

export OTEL_SERVICE_NAME=your-service-name

Note: If you use Honeycomb Classic, set the x-honeycomb-dataset in the HTTP Headers.

export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key,x-honeycomb-dataset=your-dataset-name"

Set the endpoint in SDK initialization code:

  • For OTLP/gRPC, the URI is api.honeycomb.io:443
  • For OTLP/HTTPS, the URIs are:
    • https://api.honeycomb.io/v1/traces for traces
    • https://api.honeycomb.io/v1/metrics for metrics
    • https://api.honeycomb.io/v1/logs for logs

For HTTP requests, define the API key in the HTTP headers.

For example, in Rust, it may look like this:

//...
const API_KEY: &str = "your-api-key-here";

//...

.with_headers(HashMap::from([
    ("x-honeycomb-team".into(), API_KEY.into())
    //...
]))

Finally, set the service name in the OTEL_SERVICE_NAME environment variable.

export OTEL_SERVICE_NAME=your-service-name

Note: If you use Honeycomb Classic, set the x-honeycomb-dataset in the HTTP Headers.

About the OTEL_EXPORTER_OTLP_ENDPOINT environment variable 

When using the OTEL_EXPORTER_OTLP_ENDPOINT environment variable with an SDK and an HTTP exporter, the final path of the endpoint is actually 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. The same modification is not necessary for gRPC.

By setting OTEL_EXPORTER_OTLP_ENDPOINT to https://api.honeycomb.io, traces are sent to https://api.honeycomb.io/v1/traces and metrics to https://api.honeycomb.io/v1/metrics.

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io

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
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://api.honeycomb.io/v1/metrics

More details about endpoints and signals can be found in the OpenTelemetry Specification.

Instrumented Fields 

With its Automatic Instrumentation, OpenTelemetry automatically tracks trace and span relationships using the following fields:

Field Description
name The name of the function or method where the span was created
service.name The name of the instrumented service
duration_ms How much time the span took, in milliseconds
trace.span_id The unique ID for each span
trace.trace_id The ID of the trace this span belongs to
trace.parent_id The ID of this span’s parent span, the call location the current span was called from
On this page: