Beelines and OpenTelemetry | Honeycomb

We use cookies or similar technologies to personalize your online experience & tailor marketing to you. Many of our product features require cookies to function properly.

Read our privacy policy I accept cookies from this site

Beelines and OpenTelemetry

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.

Beelines vs. OpenTelemetry  🔗

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

When Should I Use OpenTelemetry?  🔗

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:

  • Sampling is not supported well in OpenTelemetry yet. Honeycomb’s distributions for various OpenTelemetry SDKs offer deterministic sampling. But if you have more advanced sampling needs, you may need to set up a Refinery instance, or use a Beeline with an appropriate sampling strategy.
  • A given Beeline may offer automatic instrumentation for a library or framework that the equivalent OpenTelemetry SDK does not, although this situation unlikely to remain true with the community’s continued work on OpenTelemetry.
  • OpenTelemetry offers much broader language support than Beelines. A list of SDKs can be found at the OpenTelemetry Registry.

When Should I Use Beelines?  🔗

We generally do not recommend using Beelines for new instrumentation, with the exception of:

  • If you have sampling needs that a Beeline can provide, and do not wish to set up a Refinery instance
  • If you are using Ruby on Rails, the automatic instrumentation provided by Beelines is currently more robust than the Ruby OpenTelemetry SDK

Some additional points to consider with Beelines:

  • Beelines are in maintenance. They are stable and will receive bug fixes and some community contributions, but they will not receive new features.
  • 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.
  • Honeycomb has supported Beelines for Go, Python, Ruby, Java and JavaScript.

Mixing Beelines and OpenTelemetry  🔗

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:

Tracing Interoperability  🔗

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.

Do not mix Beelines and OpenTelemetry Instrumentation in the Same Process  🔗

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.

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

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 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 support@honeycomb.io and we will send you a new one.