Markers indicate points in time on your graphs where interesting things happen, such as deploys or outages. You can list, create, update, and delete Markers. The Marker UI is illustrated in the section on manually creating markers.
Marker objects have the following assignable fields. All fields are optional, and may be modified at any time.
start_time
: Indicates the time the Marker should be placed. If missing, defaults to the time the request arrives at the API. Expressed in Unix Time, aka seconds since the epochend_time
: Optional. Specifying end time will allow you to record a Marker representing a time range, such as a 5 minute deploy. This range will be highlighted when rendering a graph. Expressed in Unix Time, aka seconds since the epochmessage
: a string describing this specific Marker. This string will appear above the Marker line on a graphtype
: a string grouping similar Markers, eg ‘deploys’. All Markers of the same type will appear in the same color on the graphurl
: a target for the Marker. If you click on the Marker text, it will take you to this URL. For a deploy, this field might be a link to the build system showing the build log for the version that was deployedWhen a Marker is created or updated, the following fields are assigned. They may not be modified.
id
: The Marker ID is a 6 character hexadecimal string and is assigned on Marker creationcreated_at
: The time the Marker was createdupdated_at
: The time of the most recent modification to the Marker. It is updated every time the Marker is changed.color
: You can assign a color to a Marker type in the Dataset Advanced settings page in the UI. The color field will be populated when you list events.
The only expected header is X-Honeycomb-Team
, which is your API key, and it is required.
The API key must have the Manage Markers permission.
Learn more about API keys.
Dataset Markers are created by sending a POST request to /1/markers/<DATASET_NAME>
The Dataset Marker body should be a JSON encoded object and include as many of the Marker fields as desired. ID may not be set during creation.
When a Dataset Marker is successfully created, the API will respond with HTTP status 201
and will return a JSON object representing that Dataset Marker.
An example, creating a deploy
Marker on the TestViaCurl
dataset:
curl https://api.honeycomb.io/1/markers/test-via-curl -X POST \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '{"message":"backend deploy #123", "type":"deploy", "start_time":1471040808}'
{
"created_at": "2016-08-13T05:39:42Z",
"updated_at": "2016-08-13T05:39:42Z",
"start_time": 1471040808,
"message": "backend deploy #123",
"type": "deploy",
"id": "d1c84ec0"
}
Any of the modifiable fields in a Dataset Marker can be updated by sending a PUT request to /1/markers/<dataset>/<marker_id>
.
The PUT request should have as its body a JSON object containing all the user-settable fields for this Dataset Marker, including any updated values. If you do not include an existing field in the payload, it will be erased.
When a Dataset Marker has been successfully updated, the API returns code 200
and the updated Dataset Marker as the body of the response.
As an example, this curl request will change the start time of the Dataset Marker created above:
curl https://api.honeycomb.io/1/markers/test-via-curl/d1c84ec0 -X PUT \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '{"message":"backend deploy #123", "type":"deploy", "start_time":1471067108}'
{
"created_at": "2016-08-13T05:39:42Z",
"updated_at": "2016-08-13T05:39:42Z",
"start_time": 1471067108,
"message": "backend deploy #123",
"type": "deploy",
"id": "d1c84ec0"
}
Dataset Markers may be deleted by sending a DELETE
request to /1/markers/<dataset>/<marker_id>
.
The body of the DELETE
request should be empty.
When the Dataset Marker has been successfully deleted, the API will respond with 200
and the deleted Marker in the body of the response.
As an example, this curl request will delete the Dataset Marker we created and modified above:
curl https://api.honeycomb.io/1/markers/test-via-curl/d1c84ec0 -X DELETE \
-H "X-Honeycomb-Team: YOUR_API_KEY"
{
"created_at": "2016-08-13T05:39:42Z",
"updated_at": "2016-08-13T05:39:42Z",
"start_time": 1471067108,
"message": "backend deploy #123",
"type": "deploy",
"id": "d1c84ec0"
}
All the Markers in a dataset may be retrieved by sending a GET
request to /1/markers/<DATASET_NAME>
.
A successful response will return HTTP 200
and a JSON list of all Marker objects for the dataset.
Invalid input will result in a HTTP 422
being returned.
curl https://api.honeycomb.io/1/markers/DATASET_NAME \
-X GET -H "X-Honeycomb-Team: YOUR_API_KEY"
Honeycomb Classic users do not have environments and therefore cannot use environment markers.
Environment markers can be managed with the same APIs as above, using the special __all__
token in the URL instead of a dataset name.
Environment markers not associated with a dataset. Instead, they are visible by default on all datasets within an environment and can be toggled within the Filter Markers UI:
All API actions above are available to environment markers as well (create, list, update, delete).
curl https://api.honeycomb.io/1/markers/__all__ -X POST \
-H "X-Honeycomb-Team: YOUR_API_KEY" \
-d '{"message":"Postgres upgrade", "type":"infra", "start_time":1471040808}'
Did you find what you were looking for?