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.

For more structured learning, check out the OpenTelemetry Foundations course from Honeycomb Academy.

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 1.0 for traces, metrics, and logs. 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:

OpenTelemetry for Go

Instrument your Go application with OpenTelemetry.

OpenTelemetry for Java

Instrument your Java application with OpenTelemetry.

OpenTelemetry for .NET

Instrument your .NET application with OpenTelemetry.

OpenTelemetry for Node.js

Instrument your Node.js application with OpenTelemetry.

OpenTelemetry for Python

Instrument your Python application with OpenTelemetry.

OpenTelemetry for Ruby

Instrument your Ruby application 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.

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.

Environment Variables
In Code

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/

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

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())
    //...
]))

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`	Name of the function or method where the span was created
`service.name`	Name of the instrumented service
`duration_ms`	Length of time the span took, in milliseconds
`trace.span_id`	Unique identifier for each span
`trace.trace_id`	Unique identifier of the trace this span belongs to
`trace.parent_id`	Unique identifier of this span’s parent span, which is the call location this span was called from

​Instrumenting with OpenTelemetry

​Using the Honeycomb OpenTelemetry Endpoint

​About the OTEL_EXPORTER_OTLP_ENDPOINT environment variable

​Instrumented Fields

Instrumenting with OpenTelemetry

Using the Honeycomb OpenTelemetry Endpoint

About the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable

Instrumented Fields