1. Docs
2. Troubleshoot
3. Recommended Migrations

Recommended Migrations

Table of Contents

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 Flexible Boards 

Honeycomb Boards have a new Flexible Boards format, which allows for dynamic rearranging and resizing display options. To continue using your existing Boards, you must migrate legacy Boards to the Flexible Board format.

Existing Migration Options:

• Migrate existing legacy Boards individually through the Honeycomb UI
• Change the provided fields in your API payload for Boards managed via the Honeycomb API
• Update your Terraform configuration to use the honeycombio_flexible_board resource for Boards managed by Hashicorp Terraform

Migrate an Individual Board in the UI 

1. Visit your Board in the Honeycomb UI.
2. Select Preview as Flexible Board in the banner to preview your Board before you migrate.
3. If satisfied with the preview, select Migrate board now to finish your Board migration.

Migrate Your Boards Using the Public API 

The Flexible Board’s API request and response contain the following new fields:

• panels, which replaces the queries and slos fields from legacy Boards. View more details about panels in our Honeycomb API documentation.
• type, or board type, has a new value of flexible, which replaces the default value of classic for legacy Boards. View more details about type in our Honeycomb API documentation.

To migrate your existing Create Board or Update Board scripts:

1. Replace or add type:flexible to your API request payload
2. Remove the following deprecated fields:
   • column_layout
   • style
3. Replace any queries and slos fields with panels

Example: Migrate Your Boards Using the Public API 

Here is an example of a legacy Board API queries and slos payload, and the steps taken to migrate from legacy to Flexible Board:

{
    "queries": [
      {
        "query_style": "graph",
        "dataset": "My Dataset",
        "query_id": "abc1234e",
        "query_annotation_id": "e4c24a35",
        "visualization_settings": {
          "hide_compare": false,
          "hide_hovers": false,
          "hide_markers": false,
          "utc_xaxis": false,
          "overlaid_charts": false,
          "charts": [
            {
              "chart_index": 0,
              "chart_type": "default",
              "log_scale": false,
              "omit_missing_values": false
            }
          ]
        }
      }
    ],
    "slos": [
      "BGfyxhFto",
      "dF1URaPGL"
    ]
  }

1. First, create your new payload with panels:

   {
     "panels": []
   }
   

2. Add your slo panels. It is a one-to-one (1:1) mapping between slo and panels, so one panel per SLO is required. For example, for two SLOs, you will need two slo panels:

   {
     "panels": [
       {
         "type": "slo",
         "slo_panel": {
           "slo_id": "BGfyxhFto"
         },
       },
       {
         "type": "slo",
         "slo_panel": {
           "slo_id": "dF1URaPGL"
         },
       },
     ]
   }
   

3. Add your query panels. Similar to slo panels, query panels are a one-to-one (1:1) mapping, so one panel per query is required.

   {
     "panels": [
       {
         "type": "slo",
         "slo_panel": {
           "slo_id": "BGfyxhFto"
         },
       },
       {
         "type": "slo",
         "slo_panel": {
           "slo_id": "dF1URaPGL"
         },
       },
       {
         "type": "query",
         "query_panel": {
           "query_id": "abc1234e",
           "query_annotation_id": "e4c24a35",
           "query_style": "graph",
           "visualization_settings": {
             "hide_compare": false,
             "hide_hovers": false,
             "hide_markers": false,
             "utc_xaxis": false,
             "overlaid_charts": false,
             "charts": [
               {
                 "chart_index": 0,
                 "chart_type": "default",
                 "log_scale": false,
                 "omit_missing_values": false
               }
             ]
           }
         }
       }
     ]
   }
   

Migrate Your Boards Managed by Hashicorp Terraform 

To change, update your Terraform configuration to Flexible Board:

1. Ensure that you are using v0.35.0 of the Honeycomb.io Terraform provider.
2. Replace honeycombio_board resource blocks with honeycombio_flexible_board blocks
3. Update your configuration fields to replace query and slo blocks with panel blocks

Example: Migrate Your Boards Managed by Hashicorp Terraform 

Here is an example of a legacy Board Terraform configuration file, and the steps taken to migrate from legacy to Flexible Board:

data "honeycombio_query_specification" "latency_by_userid" {
  time_range = 86400
  breakdowns = ["app.user_id"]

  calculation {
    op     = "HEATMAP"
    column = "duration_ms"
  }

  calculation {
    op     = "P99"
    column = "duration_ms"
  }

  filter {
    column = "trace.parent_id"
    op     = "does-not-exist"
  }

  order {
    column = "duration_ms"
    op     = "P99"
    order  = "descending"
  }
}

resource "honeycombio_query" "latency_by_userid" {
  dataset    = var.dataset
  query_json = data.honeycombio_query_specification.latency_by_userid.json
}

resource "honeycombio_query_annotation" "latency_by_userid" {
  dataset     = var.dataset
  query_id    = honeycombio_query.latency_by_userid.id
  name        = "Latency by User"
  description = "A breakdown of trace latency by User over the last 24 hours"
}

resource "honeycombio_board" "overview" {
  name        = "Service Overview"

  query {
    caption             = "Latency by User"
    query_id            = honeycombio_query.latency_by_userid.id
    query_annotation_id = honeycombio_query_annotation.latency_by_userid.id

    graph_settings {
      utc_xaxis = true
    }
  }

  slo {
    id = var.slo_id
  }
}

1. Create a honeycombio_flexible_board resource:

   resource "honeycombio_flexible_board" "overview" {
   
     }
   

2. For each of your slo blocks in honeycombio_board resource, create an equivalent panel block:

   resource "honeycombio_flexible_board" "overview" {
     panel {
       type = "slo"
       slo_panel {
         slo_id = var.slo_id
       }
     }
   }
   

3. For each of your query blocks in honeycombio_board resource:

   • Create an equivalent panel block in your honeycombio_flexible_board resource
   • Replace graph_settings blocks with visualization_settings blocks

   resource "honeycombio_flexible_board" "overview" {
     panel {
       type = "slo"
       slo_panel {
         slo_id = var.slo_id
       }
     }
     panel {
       type = "query"
       query_panel {
         query_id = honeycombio_query.latency_by_userid.id
         query_annotation_id = honeycombio_query_annotation.latency_by_userid.id
   
         visualization_settings {
           use_utc_xaxis = true
         }
       }
     }
   }
   

4. Replace the honeycombio_board block with your newly created honeycombio_flexible_board block. Your final configuration should look similar to the example below:

   data "honeycombio_query_specification" "latency_by_userid" {
     time_range = 86400
     breakdowns = ["app.user_id"]
   
     calculation {
       op     = "HEATMAP"
       column = "duration_ms"
     }
   
     calculation {
       op     = "P99"
       column = "duration_ms"
     }
   
     filter {
       column = "trace.parent_id"
       op     = "does-not-exist"
     }
   
     order {
       column = "duration_ms"
       op     = "P99"
       order  = "descending"
     }
   }
   
   resource "honeycombio_query" "latency_by_userid" {
     dataset    = var.dataset
     query_json = data.honeycombio_query_specification.latency_by_userid.json
   }
   
   resource "honeycombio_query_annotation" "latency_by_userid" {
     dataset     = var.dataset
     query_id    = honeycombio_query.latency_by_userid.id
     name        = "Latency by User"
     description = "A breakdown of trace latency by User over the last 24 hours"
   }
   
   resource "honeycombio_flexible_board" "overview" {
     panel {
       type = "slo"
       slo_panel {
         slo_id = var.slo_id
       }
     }
     panel {
       type = "query"
       query_panel {
         query_id = honeycombio_query.latency_by_userid.id
         query_annotation_id = honeycombio_query_annotation.latency_by_userid.id
   
         visualization_settings {
           use_utc_xaxis = true
         }
       }
     }
   }
   

Migrate from FID to INP in the Honeycomb Web Instrumentation Package 

The Honeycomb Web Instrumentation package for the Honeycomb OpenTelemetry Web SDK now uses web-vital v5.0.0, which removes support for the fid (First Input Delay) vital. To continue capturing meaningful responsiveness metrics, we recommend switching to inp (Interaction to Next Paint). While FID only measures the delay before the browser processes a user’s first interaction, INP captures the latency of the slowest qualifying interaction on the page. It provides a more complete view of user-perceived responsiveness over the full page lifecycle.

Configuration Changes 

To migrate, replace fid with inp in your WebVitalsInstrumentationConfig. The configuration structure remains the same, though inp uses a slightly different type: VitalOptsWithTimings, which includes additional timing details.

Deprecated FID Attributes 

If you’re still using FID, these are the span attributes it produces. Each has a direct INP equivalent with a similar structure.

Migrate from Global Search 

As of January 2, 2025, the Global Search feature, which returns results from multiple Honeycomb features in one interface, is no longer available.

Instead of using Global Search, you can search for specific terms using the search box in each feature’s interface for the following Honeycomb features:

• Boards with Team permissions - Navigate to Boards using the left navigation menu.
• Datasets - Navigate to the Datasets list.
• Dataset fields - Navigate to the dataset’s Dataset Settings > Schema tab > Unique Fields section.
• Calculated Fields - Navigate to the dataset’s Dataset Settings > Schema tab > Calculated Fields section.
• Environments - Navigate to the Environments page.
• Triggers: Navigate to Triggers using the left navigation menu.
• SLOs: Navigate to SLOs using the left navigation menu.

Migrate from Honeycomb OpenTelemetry Distribution to OpenTelemetry 

If you are using a Honeycomb OpenTelemetry Distribution, an older set of Honeycomb wrappers for instrumenting code with OpenTelemetry, we recommend migrating your instrumentation to the official OpenTelemetry tooling that is supported by many vendors, including Honeycomb.

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 Honeycomb OpenTelemetry Distribution.

Resources 

To learn how to migrate from Honeycomb OpenTelemetry Distribution to OpenTelemetry, visit Migrate from Honeycomb OpenTelemetry Distribution to OpenTelemetry.

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

• Honeycomb OpenTelemetry Distribution for Go Reference
• Honeycomb OpenTelemetry Distribution for Java Reference
• Honeycomb OpenTelemetry Distribution for Node.js Reference
• Honeycomb OpenTelemetry Distribution for Python Reference
• Honeycomb OpenTelemetry Distribution for .NET Reference

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
• Calculated Fields
• 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.

Resources 

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

Resources 

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

Resources 

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.

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.

Resources 

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:

• Beeline for Go Reference
• Beeline for Java Reference
• Beeline for Node.js Reference
• Beeline for Python Reference
• Beeline for Ruby 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.

Resources 

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.

Migrate from meta.span_type in Span Events and Attributes 

The use of the field meta.span_type to identify Span Events and Span Links (hereafter called Span Annotations) was removed as of 2020-09-30. Note that this only applies to using the field meta.span_type to identify Span Annotations.

What This Change Means 

Datasets that use the field meta.span_type to identify Span Annotations will continue to work as they do now.

Teams are encouraged to migrate their systems to use meta.annotation_type to identify Span Annotations.

Honeycomb will no longer provide feature enhancements or bug fixes for Span Annotations that use meta.span_type as their identifying field.

How to Migrate Your Instrumentation if you use Span Annotations 

OpenTelemetry Exporter Users 

Upgrade to the latest version of your OpenTelemetry Exporter.

Users of Other Instrumentation Types 

For example, Beelines, OpenTracing, and so on.

Update your instrumentation code to replace the field name meta.span_type with the field name meta.annotation_type.

OR

If you use your own field name to identify Span Annotations, you do not need to change your instrumentation code. Instead:

1. Go to your Dataset Settings > Definitions tab
2. Set the field Metadata: Annotation Type to your field name.
3. Set the field Metadata: Kind to blank by clicking the X to remove assignment on this field.
4. Save your changes.

Read more on the Definitions tab.

Did you find what you were looking for?

Yes No

---

If you have questions, join our Pollinators Community Slack!
Pro/Enterprise users can visit Honeycomb Support or email support@honeycomb.io.

Submit