Annotations and Events API

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.
Create an annotation
This snippet of code will create an annotation with the tags “deployment” and “feature”, titled “New Super-duper Feature”:
curl -X POST https://[email protected]/api/v1/annotations/events/ -d \
"&title=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.
The API uses basic HTTP authorization. An example using curl:
curl -X POST https://[email protected]/api/v1/annotations/events/
curl -u 'YOUR-API-KEY:' -X POST

Delete an annotation
Curl example:
curl -X DELETE https://[email protected]/api/v1/annotations/events/ \
-d '{"title": "New Super-duper Feature", "timestamp": 1431607046}'

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:
curl -X POST https://[email protected]/api/v1/graphite/events/ \
-d '{"what": "New Super-duper Feature", "when":1431607046, "tags":"deployment feature"}'
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
annotations("restart", "deployment")
This version queries all annotations with the tags “restart” and “deployment” for the time period selected
The graphite events function events() is also available:
drawAsInfinite(events("restart", "deployment")

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:
Locate annotations in dashboard settings
  • 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):
Configure the annotation query with tags
  • You can now see annotations rendered on your graph, and can hover over the base to see the tags and description:
Visualize annotations