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.

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.

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

curl -X POST https://YOUR-API-KEY@api.hostedgraphite.com/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://YOUR-API-KEY@api.hostedgraphite.com/api/v1/annotations/events/

or

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

Delete an annotation

DELETE /api/v1/annotations/events/

Path Parameters

Name
Type
Description

title*

String

timestamp*

String

Curl example:

curl -X DELETE https://YOUR-API-KEY@api.hostedgraphite.com/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://YOUR-API-KEY@api.hostedgraphite.com/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:

  • 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