Annotations and Events API

Contents

• Annotations and Events API

  • Creating an annotation

  • Delete a single event

  • Graphite Events

    • Graphite Composer

  • Dashboard Annotations

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

Create 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

Name	Type	Description
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.

201: Created

400: Bad Request

This snippet of code will create an annotation with the tags “deployment” and “feature”, titled “New Super-duper Feature”:

curl -X POST https://[e-mail]/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://[e-mail]/api/v1/annotations/events/

or

curl -u 'YOUR-API-KEY:' -X POST https://api.hostedgraphite.com/api/v1/annotations/events/

---

Delete a single event

Delete an annotation

DELETE /api/v1/annotations/events/

Path Parameters

Name	Type	Description
title*	String
timestamp*	String

200: OK

400: Bad Request

Curl example:

curl -X DELETE https://[e-mail]/api/v1/annotations/events/ \
     -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 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://[e-mail]/api/v1/graphite/events/ \
     -d '{"what": "New Super-duper Feature", "when":1431607046, "tags":"deployment feature"}'

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:

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")

---

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:

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