Annotations and Events

Hosted Graphite now supports Annotations and Graphite Events. The Annotations feature is designed as a simpler interface to create events with tags.

What is an annotation?

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 (for the impatient)

This snippet of code will create an annotation with the tags “deployment” and “feature”, titled “New Super-duper Feature”. It’ll be timestamped at the time the event is received.

curl -X POST -d \
"&title=New Super-duper Feature\

More details about the Annotations API


Annotations have the following properties:

  • title - (required) A short summary of the annotation.
super-duper feature updated to v0.0.12
  • description - A more in-depth description of the annotation.
Slow rollout of new super-duper feature: 9b562b2. Relies on old version: 4ec124b4.
Enables the new super-duper feature in production.
  • tags - A single word or multiple short strings (all case-insensitive) to organize different types of events. e.g. ‘deployments’, ‘feature’, ‘test’ etc.
  • start_time - Unix timestamp describing when the event occurred. If this is not specified, the time of event creation is used.
  • end_time - 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.

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


curl -u 'YOUR-API-KEY:' -X POST

Delete a single event

Deleting an annotation via the API is as simple as this:

curl -X DELETE \
     -d '{"title": "New Super-duper Feature", "timestamp": 1431607046}'

Graphite Events

Events as per the Graphite project are fully supported. Insertion and rendering of Graphite Events works the same as the annotations endpoint, though the Graphite events API takes a JSON formatted data structure.

Create a single event

curl -X POST \
     -d '{"what": "New Super-duper Feature", "when":1431607046, "tags":"deployment feature"}

Graphite Composer


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

Annotations functions in the Graphite composer


The graphite events function events() is also available:

drawAsInfinite(events("restart", "deployment")
Graphite events functions in the Graphite composer

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.
Open the annotations panel in your primary dashboard
  • Set the datasource to ‘hostedgraphite’ and use the ‘Graphite event tags’ input box to filter by tags.
Fetching events tagged with "deployment" and "feature"
  • Individual wildcards also work to display all events.
Fetching all events