Annotate the Timeline with Markers | Honeycomb

Annotate the Timeline with Markers

Markers signal interesting occurrences within the context of your queries.

Use Markers to identify points in time, such as:

  • Deploys
  • Incidents
  • Activated/resolved Triggers
  • On/Off feature flags

Markers can apply to an entire environment or a specific dataset. Create an environment marker when the range of time is relevant across multiple datasets and Services, such as a deployment marker. Create a dataset marker when the range of time is relevant to the specific dataset or Service.

Note
Honeycomb Classic does not support Environment markers. Learn more about Honeycomb versus Honeycomb Classic.

View Markers in the UI 

Once created, markers appear on any queries that run within the same time period as the marker(s).

Each marker type can appear in its own color.

Tip
To change marker color, configure dataset markers in Dataset Settings or environment markers in Environment Settings.

Hover over the downward caret icon to view a marker’s details. A solid vertical line appears and a window displays the marker’s name, description, and if applicable, a selectable URL.

To persist the marker’s vertical line and information window, select the downward caret icon. To close the persisted display, use the x icon that appears in the window after selection.

Screenshot illustrating a selected marker and marker details

Filter Markers in the UI 

By default, Honeycomb shows environment markers in environment-wide queries and dataset markers in dataset queries.

Use Filter Markers to modify what markers appear in the query results.

To access Filter Markers, either:

  1. Press l on your keyboard
  2. Select the Speech Box icon below the time picker in your query results, and select Filter Markers.

The Filter Markers modal appears. Use to modify what markers appear based on:

  1. on their value
  2. whether or not markers of the opposite type (environment/dataset) are allowed
  3. their marker type
Screenshot illustrating the 'Filter Markers' dialog box for a dataset query

Manage Markers 

Add Markers From the UI 

To create a marker from the UI:

  1. In your query results, move your cursor over the graph to your desired time point.
  2. Select your desired time point, which causes the graph menu options to appear.
  3. Select Add marker. The Add a Marker modal appears. Screenshot illustrating the 'Add a Marker' dialog box
  4. Enter the following information:
    1. A Message for your marker, such as “Deploy #299” or “Abnormal Spike in Products Page Traffic”.
    2. A Type for the marker, such as “deploy” or “trigger”. After creation, the type appears as a preface to the marker’s message when viewing the marker details.
    3. The URL field is optional, but provides a great way for more context about the marker.
    4. Select the “Environment-wide” checkbox to apply this marker to all datasets in your environment.
      Note
      Honeycomb Classic users must migrate first to use this Environment-wide feature.
  5. When finished, select Create to add your marker to the graph.
Tip
To delete a marker, use the available command line options.

Add Markers (add

To add markers via a command line tool, use either curl or honeymarker, a lightweight marker management tool that provides a CRUD command line interface.

For example:

honeymarker \
    -k YOUR_API_KEY \
    -d myservice \
    -t deploy \
    -m "build 192837" \
    add
curl https://api.honeycomb.io/1/markers/myservice -X POST \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '{"message":"build 192837", "type":"deploy"}'
Note
To use our EU instance, post your data to https://api.eu1.honeycomb.io/1/markers/myservice instead.

honeymarker add 

honeymarker has the following command line flags:

Name Flag Description Required
Start Time -s <arg> / --start_time=<arg> start time for the marker in unix time (seconds since the epoch) No
End Time -e <arg> / --end_time=<arg> end time for the marker in unix time (seconds since the epoch) No
Message -m <arg> / --msg=<arg> message describing this specific marker No
URL -u <arg> / --url=<arg> URL associated with this marker No
Type -t <arg> / --type=<arg> identifies marker type No

All parameters to add are optional.

If start_time is missing, the marker will be assigned the current time.

It is highly recommended that you fill in either message or type. All markers of the same type will be shown with the same color in the UI. The message will be visible above an individual marker.

If a URL is specified along with a message, the message will be shown as a link in the UI, and clicking it will take you to the URL.

List Markers (list

To list markers via a command line tool, use either curl or honeymarker, a lightweight marker management tool that provides a CRUD command line interface.

For example:

honeymarker \
    -k YOUR_API_KEY \
    -d myservice \
    list
curl https://api.honeycomb.io/1/markers/myservice -X GET \
    -H "X-Honeycomb-Team: YOUR_API_KEY"
Note
To use our EU instance, get data from https://api.honeycomb.io/1/markers/myservice instead.

honeymarker list 

honeymarker has the following command line flags:

Name Flag Description Required
JSON --json Output the list as json instead of in tabular form No
Unix Timestamps --unix_time In table mode, format times as unit timestamps (seconds since the epoch) No

Update Markers (update

To update markers via a command line tool, use either curl or honeymarker, a lightweight marker management tool that provides a CRUD command line interface.

For example:

honeymarker \
    -k YOUR_API_KEY \
    -d myservice \
    -i marker-id \
    -u "http://my.service.co/builds/192837" \
    update
curl https://api.honeycomb.io/1/markers/myservice/marker-id -X PUT \
    -H "X-Honeycomb-Team: YOUR_API_KEY" \
    -d '{"url":"http://my.service.co/builds/192837"}'
Note
To use our EU instance, send data to https://api.eu1.honeycomb.io/1/markers/myservice/marker-id instead.

honeymarker update 

honeymarker has the following command line flags:

Name Flag Description Required
Marker ID -i <arg> / --id=<arg> ID of the marker to update Yes
Start Time -s <arg> / --start_time=<arg> start time for the marker in unix time (seconds since the epoch) No
End Time -e <arg> / --end_time=<arg> end time for the marker in unix time (seconds since the epoch) No
Message -m <arg> / --msg=<arg> message describing this specific marker No
URL -u <arg> / --url=<arg> URL associated with this marker No
Type -t <arg> / --type=<arg> identifies marker type No

The marker ID is available from the list command, and is also output to the console by the add command.

Delete Markers (rm

To delete markers via a command line tool, use either curl or honeymarker, a lightweight marker management tool that provides a CRUD command line interface.

For example:

honeymarker \
    -k YOUR_API_KEY \
    -d myservice \
    -i marker-id \
    rm
curl https://api.honeycomb.io/1/markers/myservice/marker-id -X DELETE \
    -H "X-Honeycomb-Team: YOUR_API_KEY"
Note
To use our EU instance, delete data from https://api.eu1.honeycomb.io/1/markers/myservice/marker-id instead.

honeymarker delete 

honeymarker has the following command line flags:

Name Flag Description Required
Marker ID -i <arg> / --id=<arg> ID of the marker to delete Yes

The marker ID is available from the list command, and is also output to the console by the add command.

Honeymarker 

honeymarker is a lightweight tool that provides a CRUD command line interface to manage your markers.

Installation 

Download and install the latest version of honeymarker by visiting the releases page for v0.2.11 of honeymarker, which contains binary packages for a variety of platforms. The packages install honeymarker to /usr/bin. The binary is called honeymarker, available if you need it in an unpackaged form or for ad-hoc use.

View honeymarker’s source here.

Usage 

Use the following command format for honeymarker:

honeymarker -k <YOUR_API_KEY> -d <dataset> COMMAND [command-specific flags]

where:

Note
For Environment markers, use __all__ for dataset name.

Available Commands 

honeymarker has the following commands:

Command Description
add add a new marker
list list all markers
rm delete a marker
update update a marker

OpenTelemetry Marker Exporter 

The OpenTelemetry Collector’s Marker Exporter allows you to send a Honeycomb Marker based on the shape of incoming telemetry.

In your OpenTelemetry Collector exporter configuration, you can specify a set of rules that will be evaluated against incoming telemetry. When a condition is met, a marker is sent and appears in Honeycomb. For example, whenever a Kubernetes Event contains a reason of Backoff, the configuration below sends a marker:

exporters:
  honeycombmarker:
    api_key: YOUR-API-KEY-HERE
    markers:
      # Creates a new marker each time the exporter sees a Kubernetes event with a reason of Backoff
      - type: k8s-backoff-events
        rules:
          - log_conditions:
              - IsMap(body) and IsMap(body["object"]) and body["object"]["reason"] == "Backoff"