Recommended Migrations | Honeycomb

Recommended Migrations

We recommend that customers migrate to the new behaviors listed below.

If you have questions, visit our Support Knowledge Base or join our Pollinators Community.

Migrate to Stabilized OpenTelemetry Semantic Conventions 

OpenTelemetry HTTP semantic conventions (SemConv) became stable in 2023. As part of the breaking changes related to stabilization, 17 attributes in the HTTP semantic conventions were renamed (for example, http.status_code changed to http.request.status_code). These changes are likely to impact several areas within Honeycomb.

We recommend that you review the complete list of attribute changes in OpenTelemetry’s Summary of Changes.

With these attribute changes in mind, we also recommend that you review your Honeycomb:

  • SLOs
  • Triggers
  • Derived Columns
  • Boards and saved queries
  • Refinery rule conditions and field lists
  • OpenTelemetry Collector configurations

If any of these elements depend on attributes with HTTP semantic conventions, then you will be impacted by these breaking changes.


To find impacted instrumentation packages, as published under the OpenTelemetry GitHub organization, and the current status of their compliance with the stabilized HTTP semantic conventions, visit OpenTelemetry HTTP Semantic Conventions Compatibility.

To learn how to migrate to stabilized OpenTelemetry semantic conventions, visit Migrate to Stabilized OpenTelemetry Semantic Conventions.

Migrate to Refinery 2.0 

If you use Refinery, we recommend that you migrate to Refinery 2.0 or later to take advantage of new and improved Refinery features. Benefits of upgrading your Refinery instance to 2.0 include:

  • Improved .yaml-based configuration with better default values
  • New samplers: EMAThroughputSampler and WindowedThroughputSampler
  • Configuration file validation
  • Having all dynamic samplers now correctly count spans, not traces, to determine the sampling rate, which makes it easier to right-size sampling based on event volume
  • Improved metrics, including output as OpenTelemetry
  • Support for emitting multiple metrics sources


To learn how to migrate to Refinery 2.0 and later, visit Migrate to Refinery 2.0.

Migrate from Honeycomb Kubernetes Agent 

If you are using the Honeycomb Kubernetes Agent, we recommend that you choose a new path from our Kubernetes Overview and migrate accordingly. The Honeycomb Kubernetes Agent is in maintenance mode, and we will notify users when a deprecation date is set.


To learn more about how the Honeycomb Kubernetes Agent was installed, configured, and used, visit Honeycomb Kubernetes Agent Reference.

Migrate from Beelines to OpenTelemetry 

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 mode, and we will notify users when a deprecation date is set.

If you are not yet ready to migrate to OpenTelemetry, we recommend instrumenting any new observability efforts with OpenTelemetry while maintaining your old code instrumented with Beelines. Beelines and OpenTelemetry work well in a mixed environment and using both will allow you to get trace visualizations that include them both.


To learn how to migrate from Beelines to OpenTelemetry, visit Migrate from Beelines to OpenTelemetry.

To learn more about how Beelines were installed, configured, and used, visit the appropriate reference:

Migrate from Honeycomb Classic to Honeycomb Environments 

If you are using Honeycomb Classic, we recommend that you migrate to Honeycomb Environments and Services, so you can take advantage of its expanded data model that includes environments and services groupable, relational structures. Benefits of migrating from Honeycomb Classic to Honeycomb Environments include:

  • Simplified, organized dataset schemas : The groupable, relational structures of datasets in an Environment allow for focused datasets with relevant fields and values rather than an all-in-one dataset. Each service in an Environment gets its own Dataset, and each Dataset is less likely to exceed the 20,000 field limit.

  • Query across all datasets or a specific dataset : Query all the datasets in the Environment, as if it were in a single Dataset, or scope your query to a specific Dataset. The Query Builder provides auto-complete suggestions based on the scope of the query.

  • Scale and add new services : Services added to an Environment create new Datasets instead of impacting existing ones.

  • Dataset-specific Home Page : A dataset dedicated to one service presents relevant information on its Home page as the Dataset Definitions map more meaningfully to the service’s fields.

  • Define Markers for an Environment : Annotate an important moment across all of its Datasets with a Marker. For example, use a Marker to indicate a new deployment in the Production Environment.

  • Better security : API keys are scoped per Environment instead of per Team, which allows securing critical instances, like your Production environment.

Future product updates will support only the Environments and Services model. For example, Service Map only supports datasets within an Environment.

Am I Using Honeycomb Classic? 

If your Honeycomb team existed before the Honeycomb Environments and Services change, you have a Classic environment.

To be sure, look for a label below Honeycomb logo in the Honeycomb UI. Honeycomb Classic environments have a Classic label with a gray background.

The environment selector set to Classic (screenshot)


To learn how to migrate from Honeycomb Classic to Environments, visit Migrate from Honeycomb Classic.

For a checklist that can help you prepare for migration, visit Prepare to Migrate from Honeycomb Classic.

To learn more about best practices for organizing data in Honeycomb Classic, visit Best Practices for Honeycomb Classic Datasets.