If you are using Beelines, an older set of Honeycomb SDKs for instrumenting code, we recommend migrating your instrumentation to OpenTelemetry, a cross-industry standard that is supported by many vendors, including Honeycomb. Beelines are in maintenance, and we will notify users when a deprecation date is set.
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.
Honeycomb Beelines were written before OpenTelemetry. They use a format and API that can only be used with Honeycomb.
While we recommend migration all of your instrumentation to OpenTelemetry, you can instrument some services in the same environment with Beelines and some with OpenTelemetry. You will need to keep some things in mind regarding tracing interoperability, though. To learn more, check out Mixing Beelines and OpenTelemetry.
You can incrementally migrate your services from Beeline to OpenTelemetry. At a high level, this will require that you configure each Beeline instance to use the W3C trace header format, and then migrate to OpenTelemetry instrumentation. Using the W3C trace header format lets Beeline and OpenTelemetry instrumentation share trace context at the service/process level, which allows you to migrate one service at a time rather than rewriting everything at once.
Upgrade to Beeline version 1.4.0 or above. This version of Beeline will parse trace context from incoming headers by default. The order of preference when parsing these headers is: parser hook > honeycomb format > W3C format.
Configure each Beeline to propagate trace context using the W3C format. You can do this by configuring a propagation hook.
Migrate instrumentation to OpenTelemetry, paying attention to the information in Mixing Beelines and OpenTelemetry.
Upgrade to Beeline version 1.7.0 or above. This version of Beeline will parse trace context from incoming headers by default. The order of preference when parsing these headers is: parser hook > honeycomb format > W3C format.
Configure each Beeline to propagate trace context using the W3C format. You can do this by configuring a propagation hook.
Migrate instrumentation to OpenTelemetry, paying attention to the information in Mixing Beelines and OpenTelemetry.
Upgrade to Beeline version 3.2.2 or above. This version of Beeline will parse trace context from incoming headers by default. The order of preference when parsing these headers is: parser hook > honeycomb format > W3C format.
Configure each Beeline to propagate trace context using the W3C format.
const beeline = require('honeycomb-beeline');
beeline({
writeKey: 'YOUR_API_KEY',
serviceName: 'your-service-name',
httpTracePropagationHook: beeline.w3c.httpTracePropagationHook
});
Migrate instrumentation to OpenTelemetry, paying attention to the information in Mixing Beelines and OpenTelemetry.
Upgrade to Beeline version 2.18.0 or above. This version of Beeline will parse trace context from incoming headers by default. The order of preference when parsing these headers is: parser hook > honeycomb format > W3C format.
Configure each Beeline to propagate trace context using the W3C format.
import beeline
import beeline.propagation.w3c as w3c
beeline.init(
writekey='YOUR_API_KEY',
service_name='YOUR_SERVICE',
debug=True,
http_trace_propagation_hook=w3c.http_trace_propagation_hook
)
Migrate instrumentation to OpenTelemetry, paying attention to the information in Mixing Beelines and OpenTelemetry.
Upgrade to Beeline version 2.8.0 or above. This version of Beeline will parse trace context from incoming headers by default. The order of preference when parsing these headers is: parser hook > honeycomb format > W3C format.
Configure each Beeline to propagate trace context using the W3C format.
require "honeycomb-beeline"
require "honeycomb/propagation/w3c"
Honeycomb.configure do |config|
...
config.http_trace_propagation_hook do |env, context|
Honeycomb::W3CPropagation::MarshalTraceContext.parse_faraday_env env, context
end
...
end
Migrate instrumentation to OpenTelemetry, paying attention to the information in 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.
You will need to keep some things in mind regarding tracing interoperability, though.
Trace context propagation with OpenTelemetry is done by sending and parsing headers that conform to the W3C Trace Context specification.
To get Beelines and OpenTelemetry instrumentation to interoperate, you will need to use W3C headers.
The Beeline includes marshal and unmarshal functions that can generate and parse W3C Trace Context headers. Honeycomb Beelines default to using a Honeycomb-specific header format on outgoing requests, but can automatically detect incoming W3C headers and parse them appropriately. In mixed environments where some services are using OpenTelemetry and some are using Beeline, W3C header propagation should be used.
To propagate trace context, a parser hook and propagation hook are needed. The parser hook is responsible for reading the trace propagation context out of incoming HTTP requests from upstream services. The propagation hook is responsible for returning the set of headers to add to outbound HTTP requests to propagate the trace propagation context to downstream services.
Note: Older versions of Honeycomb Beelines required HTTP parsing hooks to properly parse incoming W3C headers. Current versions of Honeycomb Beelines can automatically detect incoming W3C headers and parse them appropriately. Check the release notes for your Beeline version to confirm whether an upgraded version is needed.
To specify that a service should propagate W3C Trace Context Headers with outgoing requests, you must specify a propagation hook in the beeline configuration.
You can see 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")
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 Beelines, or have a specific use case for your architecture?
The Honeycomb Pollinators Community is a great place to ask your questions and share your experience.