Honeycomb’s data ingest path supports several types of instrumentation, including two approaches specific to instrumenting code: vendor-neutral OpenTelemetry and Honeycomb’s Beelines. Both of these approaches generate the structured event data format that will help you get the most out of Honeycomb.
New to instrumenting code? Want to learn about structured events? Read more about instrumentation.
The Honeycomb Beelines were written before OpenTelemetry. They use a format and API that can only be used with Honeycomb.
OpenTelemetry is a cross-industry standard that is supported by many vendors, including Honeycomb. Data generated by OpenTelemetry can be used with Honeycomb and other OpenTelemetry-compatible tools.
In the long term, Honeycomb plans to embrace OpenTelemetry for most instrumentation concerns.
If you already use Beelines, you can continue to use them. However, we generally recommend migrating to OpenTelemetry. You do not need to rewrite all your instrumentation code up front to use OpenTelemetry. If one service is instrumented with OpenTelemetry and another with Beelines, you can still get trace visualizations that include them both. (See Mixing Beelines and OpenTelemetry below.)
We generally recommend that you use OpenTelemetry for any new instrumentation. When instrumenting a new service, first consider OpenTelemetry before using Beelines.
Some additional points to consider with OpenTelemetry:
We generally do not recommend using Beelines for new instrumentation, with the exception of:
Some additional points to consider with Beelines:
If you are already using Beelines to instrument some services, but need to instrument a new service, you do not need to continue with Beelines. You can instrument any new services with OpenTelemetry. We call this a Mixed Environment, and you can get trace visualizations from both Beeline and OpenTelemetry instrumentation.
Some things to keep in mind:
To get Beelines and OpenTelemetry instrumentation to interoperate, you will need to configure the W3C Trace Context in your Beeline to read and write OpenTelemetry’s trace headers. By default, Beelines use a Honeycomb-specific set of headers to propagate trace context. Here is an example of this configuration in the Go Beeline.
To learn more about ongoing development for W3C trace context propagation, visit the W3C Trace Context GitHub repository.
If you instrument each service or process with OpenTelemetry or a Beeline, then your data will be coherent.
The granularity with which you can mix Beelines and OpenTelemetry without additional, more advanced work, is at the process- or service-level. Do not mix them in the same process, as this will result in bad data unless you adopt a wrapper and a strategy for incrementally switching your instrumentation calls to OpenTelemetry.
The names of fields differ on events produced by the Beeline instrumentations and the OpenTelemetry instrumentations.
For example, the Beelines'
service_name field has an equivalent of
service.name in OpenTelemetry events.
To use a single column for this value in queries for the name of a service, define a derived column in the dataset and use the
COALESCE function to determine the name:
COALESCE($service.name, $service_name, "unknown")
IF( EXISTS($service.name), $service.name, EXISTS($service_name), $service_name, "unknown" )
In order to achieve trace-aware sampling across a mixed environment, all instrumented services need to send data to Honeycomb via Refinery.
Do you still have questions about OpenTelemetry and Honeycomb, or have a specific use case for your architecture?
The Honeycomb Pollinators Community Slack is a great place to ask your questions and share your experience. If you misplaced your invite, ask us via chat or email email@example.com and we will send you a new one.