Annotations and Events API
Contents
Hosted Graphite supports Annotations and Graphite Events. The Annotations feature is designed as a simpler interface to create events with tags. An annotation relates your metrics to intermittent events for example when you deploy code, run some tests (hopefully successfully), or a long-running job completes.
Creating an Annotation
POST /api/v1/annotations/events/
Create an annotation with titles, tags, and descriptions that will be time-stamped as it is received.
Path Parameters
title*
String
A short summary of the annotation.
description
String
A more in-depth description of the annotation.
tags
String
A single word or multiple short strings (all case-insensitive) to organize different types of events. e.g. ‘deployments’, ‘feature’, ‘test’ etc.
start_time
String
Unix timestamp describing when the event occurred. If this is not specified, the time of event creation is used.
end_time
String
Optional timestamp describing when the event completed. Note: We currently don’t support region events. As a result, end_time has no actual use in annotations.
Created
Bad Request
This snippet of code will create an annotation with the tags “deployment” and “feature”, titled “New Super-duper Feature”:
There’s no restriction on having annotations with the same time stamps, but the combination of start time and title must be unique.
Authentication:
The API uses basic HTTP authorization. An example using curl:
or
Delete a single event
Delete an annotation
DELETE /api/v1/annotations/events/
Path Parameters
title*
String
timestamp*
String
OK
Bad Request
Curl example:
Graphite Events
Events as per the Graphite project are fully supported. Insertion and rendering of Graphite Events work the same as the annotations endpoint, though the Graphite events API takes a JSON formatted data structure. Here's an example of creating a single Graphite event:
Graphite Composer
Annotations:
To support the display of Annotations, there is a function annotations() available in graphite to query and display the events. There are two options:
This first option with a wildcard queries all available annotations for the time period selected
This version queries all annotations with the tags “restart” and “deployment” for the time period selected
Events:
The graphite events function events() is also available:
Dashboard Annotations
The dashboard annotations feature works exactly as specified in the annotation documentation. It can be used to query by tags (not graphite targets).
To open the annotations panel, click the settings icon in the top bar and select Annotations:
Set the datasource to ‘hostedgraphite’ and use the ‘Graphite event tags’ input box to filter by tags (Individual wildcards also work to display all events):
You can now see annotations rendered on your graph, and can hover over the base to see the tags and description:
Last updated