Dataset Definitions API | Honeycomb

Honeycomb.io Documentation
  1. Docs
  2. API
  3. Dataset Definitions API

Dataset Definitions API

Dataset definitions describe the fields in your Dataset that have special meaning. Refer to the Dataset definitions documentation for more information.

Dataset Definition Type IDs 

Each Dataset definition type ID corresponds to its Dataset definition. Refer to the chart below for a list.

Use the Dataset definition type IDs when setting Dataset definitions. Define these type IDs in the URL of the request to address a single definition or in the payload to address multiple definitions.

Definition Type ID Name
span_id Span ID
trace_id Trace ID
parent_id Parent Span ID
name Name
service_name Service Name
duration_ms Span Duration
span_kind Metadata: Kind
annotation_type Metadata: Annotation Type
link_span_id Metadata: Link Span ID
link_trace_id Metadata: Link Trace ID
error Error
status HTTP Status Code
route Route
user User

Authorization and Headers 

The only expected header is X-Honeycomb-Team, which is your API key, and it is required. The API key must have the Create Datasets permission. Learn more about API keys.

Fields on a Dataset Definition 

Dataset definitions have the following fields:

Field Type Optional Notes
name string no Name of the column or derived column used for the definition
column_type string yes “column” for regular columns and “derived_column” for derived columns.

Create a Dataset Definition 

Honeycomb automatically creates these Dataset definition fields when the Dataset is created. Manual creation of Dataset definitions is not needed.

To set a Dataset definition to a new value, use the PATCH API endpoint.

Get All Dataset Definitions for a Dataset 

Use GET to retrieve all definitions for a Dataset. The response returns an object with a Dataset definition for each set Dataset definition type.

Get All Dataset Definitions Example Request  

curl https://api.honeycomb.io/1/dataset_definitions/$DATASET_SLUG \
    -X GET \
    -H "X-Honeycomb-Team: YOUR_API_KEY"

Get All Dataset Definitions Example Response  

{
  "trace_id": {
    "id": "D1TaSJzsEoX",
    "name": "your_trace_id_column_name",
    "column_type": "column"
  },
  "span_id": {
    "id": "yUheCUmgZ8p",
    "name": "your_span_id_column_name",
    "column_type": "derived_column"
  }
}

Update Dataset Definitions for a Dataset 

Use PATCH to set or update one or more definitions for a Dataset. The PATCH payload takes a map of Dataset definition type to Dataset definition. Fields not defined in the request are not modified on the server.

While the PATCH payload can include the column_type, Honeycomb does not use this field when updating Dataset definitions.

This PATCH API endpoint requires the Create Dataset permission.

Update Dataset Definitions Example Request  

curl https://api.honeycomb.io/1/dataset_definitions/$DATASET_SLUG \
    -X PATCH \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '{"trace_id": { "name": "trace.trace_id"}, "error": {"name": "err_msg"}}'

Clear a Dataset Definition 

Clear a column of a Dataset definition with the PATCH API endpoint. Set the column’s name field to an empty string.

Clear Dataset Definition Example Request 

Clear the trace_annotation_type column and link_trace_id column for the Dataset.

curl https://api.honeycomb.io/1/dataset_definitions/$DATASET_SLUG \
    -X PATCH \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '{"trace_annotation_type": { "name": ""}, "link_trace_id": {"name": ""}}'

Did you find what you were looking for?

Table of Contents