Beelines and OpenTelemetry

Honeycomb’s data ingest path supports several types of instrumentation, including two approaches specific to instrumenting code: Honeycomb’s Beelines and vendor-neutral OpenTelemetry. 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.

Beelines vs. OpenTelemetry 🔗

When Should I Use Beelines? 🔗

Beelines are Honeycomb-created libraries. They are designed to provide the strongest support for language and framework auto-instrumentation.
When you install a Beeline, Honeycomb will auto-instrument some features of your code – see the language-specific instructions for details.
Honeycomb has supported Beelines for Go, Python, Ruby, Java and JavaScript. There are also a number of community contributed Beelines.
The Beelines provide a variety of sampling options; from simple 1 in X sample rates to more complex scenarios where a user application can make the sampling decision itself. More information regarding sampling with the Beelines can be found here.

When Should I Use OpenTelemetry? 🔗

OpenTelemetry is an open standard for handling distributed trace data. The events that OpenTelemetry creates will work within Honeycomb.
OpenTelemetry is available for a wide variety of languages (albeit at different stages of maturity); a list of SDKs can be found at the OpenTelemetry Registry;
When you instrument your code with OpenTelemetry, you can use an SDK’s OTLP/gRPC exporter to send directly to Honeycomb or an OpenTelemetry Collector to gather data from multiple instrumentation clients and export to Honeycomb via OTLP/gRPC.
Sampling is currently a work in progress in OpenTelemetry where a pluggable model is used with some default samplers bundled with the SDKs. Honeycomb is working on providing compatible implementations to what the Beelines offer.

What is the Honeycomb Roadmap? 🔗

As OpenTelemetry grows to embrace more languages, Honeycomb plans to continue to support OpenTelemetry; we see OpenTelemetry as a key component of our ability to support many programming languages and environments.

Mixed Environment 🔗

You don’t need to instrument all the services in your stack the same way. If one service is instrumented with OpenTelemetry and another with Beelines, you can still get trace visualizations that include them both! Some things to keep in mind:

Tracing Interoperability 🔗

Beeline instrumentations do not read and write the OpenTelemetry trace header, W3C Trace Context, by default. To enable trace interoperability between services instrumented with Beelines and OpenTelemetry, you will need to configure the Beeline to use the W3C header for trace propagation. Here’s 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.

Field Name Differences 🔗

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")

Note: For Secure Tenancy customers, the COALESCE function is not available. Instead, use IF and EXISTS in the derived column definition:

IF( EXISTS($service.name), $service.name,
    EXISTS($service_name), $service_name,
    "unknown" )

Sampling 🔗

In order to achieve trace-aware sampling across a mixed environment, all instrumented services need to send data to Honeycomb via Refinery.

Questions and Support 🔗

Do you still have questions about OpenTelemetry and Honeycomb, or have a specific use case for your architecture? The Honeycomb Community Slack is a great place to ask your questions and share your experience–if you misplaced your invite, ask us on Intercom or email support@honeycomb.io and we’ll send you a new one.