Links

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.
post
/api/v1/annotations/events/
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\
&tag=deployment\
&tag=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:
curl -X POST https://[email protected]/api/v1/annotations/events/
or
curl -u 'YOUR-API-KEY:' -X POST https://api.hostedgraphite.com/api/v1/annotations/events/

delete
/api/v1/annotations/events/
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"}'
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:
annotations("*")
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
Events:
The graphite events function events() is also available:
drawAsInfinite(events("*")
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