Managing Markers

Here at Honeycomb, we like to say that the greatest single cause of chaos in systems is humanity. And in the case of observing systems, this generally manifests in two ways: aberrant customer behavior or changes in the code.

One of the easiest ways to highlight chaos caused by the latter is by using markers: dataset-wide points in time that indicate that an interesting thing has happened. Once you’ve created a marker at a specific time, any queries run on that dataset including that time period will display a dotted vertical line (and optional message when you mouse over it):

Screenshot illustrating a query including markers

All of these operations may be invoked via curl or via a lightweight tool named honeymarker that provides a CRUD command line interface for managing your markers.

Installation

Use curl on your machine or use our honeymarker wrapper.

Download and install the latest honeymarker by running:

wget -q https://honeycomb.io/download/honeymarker/linux/honeymarker_1.9_amd64.deb && \
      echo '5aa10dd42f4f369c9463a8c8a361e46058339e6273055600ddad50e1bcdf2149  honeymarker_1.9_amd64.deb' | sha256sum -c && \
      sudo dpkg -i honeymarker_1.9_amd64.deb

The packages install honeymarker to /usr/bin. The binary is just honeymarker, available if you need it in an unpackaged form or for ad-hoc use.

You can view honeymarker’s source here.

Usage

$ honeymarker -k <your-writekey> -d <dataset> COMMAND [command-specific flags]

Available commands:

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

Adding markers (add)

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.

Example:

$ ./honeymarker -k $YOUR_WRITE_KEY -d myservice add -t deploy -m "build 192837"
# {"created_at":"2017-06-28T18:55:11Z","updated_at":"2017-06-28T18:55:11Z","start_time":1498676111,"message":"build 192837","type":"deploy","id":"n71R3zM1Tn3"}
$ curl https://api.honeycomb.io/1/markers/myservice -X POST  \
    -H "X-Honeycomb-Team: $YOUR_WRITE_KEY"  \
    -d '{"message":"build 192837", "type":"deploy"}'
# {"id":"n71R3zM1Tn3","start_time":1498650911,"type":"deploy","message":"build 192837","created_at":"2017-09-06T18:45:00-07:00"}

Listing markers (list)

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

Example:

$ ./honeymarker -k $YOUR_WRITE_KEY -d myservice list
# | ID          |      Start Time |        End Time | Type         | Message      | URL |
# +-------------+-----------------+-----------------+--------------+--------------+-----+
# | n71R3zM1Tn3 | Jun 28 11:55:11 |                 | deploy       | build 192837 |     |
$ curl https://api.honeycomb.io/1/markers/myservice -X GET  \
    -H "X-Honeycomb-Team: $YOUR_WRITE_KEY"
# [{"id":"n71R3zM1Tn3","start_time":1498650911,"type":"deploy","message":"build 192837","created_at":"2017-09-06T18:45:00-07:00"}

Updating markers (update)

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.

Example:

$ ./honeymarker -k $YOUR_WRITE_KEY -d myservice update -i n71R3zM1Tn3 -u "http://my.service.co/builds/192837"
# {"created_at":"2017-06-28T18:55:11Z","updated_at":"2017-06-28T18:55:11Z","start_time":1498676111,"message":"build 192837","type":"deploy","url":"http://my.service.co/builds/192837","id":"n71R3zM1Tn3"}
$ curl https://api.honeycomb.io/1/markers/myservice/n71R3zM1Tn3 -X PUT  \
    -H "X-Honeycomb-Team: $YOUR_WRITE_KEY"  \
    -d '{"url":"http://my.service.co/builds/192837"}'
# {"created_at":"2017-06-28T18:55:11Z","updated_at":"2017-06-28T18:55:11Z","start_time":1498676111,"message":"build 192837","type":"deploy","url":"http://my.service.co/builds/192837","id":"n71R3zM1Tn3"}

Deleting markers (rm)

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.

Example:

$ ./honeymarker -k $YOUR_WRITE_KEY -d myservice rm -i n71R3zM1Tn3
# {"created_at":"2017-06-28T18:55:11Z","updated_at":"2017-06-28T18:57:47Z","start_time":1498676111,"message":"build 192837","type":"deploy","url":"http://my.service.co/builds/192837","id":"n71R3zM1Tn3"}

$ ./honeymarker -k $YOUR_WRITE_KEY -d myservice list
# | ID          |      Start Time |        End Time | Type         | Message | URL |
# +-------------+-----------------+-----------------+--------------+---------+-----+
$ curl https://api.honeycomb.io/1/markers/myservice/n71R3zM1Tn3 -X DELETE  \
    -H "X-Honeycomb-Team: $YOUR_WRITE_KEY"
# {"created_at":"2017-06-28T18:55:11Z","updated_at":"2017-06-28T18:57:47Z","start_time":1498676111,"message":"build 192837","type":"deploy","url":"http://my.service.co/builds/192837","id":"n71R3zM1Tn3"}

$ curl https://api.honeycomb.io/1/markers/myservice -X GET  \
    -H "X-Honeycomb-Team: $YOUR_WRITE_KEY"
# []