Send Data with 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, we recommend using OpenTelemetry.

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

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, Zipkin, or Jaeger, you should use an OpenTelemetry Collector to convert into OTLP and export your data to Honeycomb.

Instrumenting with OpenTelemetry 

Select your application’s language for instructions on instrumenting 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.

  1. Set the endpoint:

    • For OTLP/gRPC:
      • US instance: export OTEL_EXPORTER_OTLP_ENDPOINT=api.honeycomb.io:443
      • EU instance: export OTEL_EXPORTER_OTLP_ENDPOINT=api.eu1.honeycomb.io:443
    • For OTLP/HTTPS:
      • US instance: export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io/
      • EU instance: export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.eu1.honeycomb.io/
  2. Set your API key:

    export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=your-api-key"
    
  3. 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"
    
  1. Set the endpoint in SDK initialization code:

    • For OTLP/gRPC:
      • US instance: api.honeycomb.io:443
      • EU instance: api.eu1.honeycomb.io:443
    • For OTLP/HTTPS:
      • US instance:
        • https://api.honeycomb.io/v1/traces for traces
        • https://api.honeycomb.io/v1/metrics for metrics
        • https://api.honeycomb.io/v1/logs for logs
      • EU instance:
        • https://api.eu1.honeycomb.io/v1/traces for traces
        • https://api.eu1.honeycomb.io/v1/metrics for metrics
        • https://api.eu1.honeycomb.io/v1/logs for logs
  2. 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())
        //...
    ]))
    
  3. 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 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.

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