Hosted Graphite Docs
Get StartedBook a Demo
  • Welcome to Hosted Graphite
  • Getting Started
  • HG-CLI
  • Sending Metrics
    • Supported Protocols
    • Graphite Tag Support
    • Metric Management
    • Metric APIs
  • Language Guide
    • Metric Libraries
    • .NET
    • Go
    • Java
    • Javascript
    • Node.js
    • PHP
    • Postman
    • Python 2.x
    • Python 3.x
    • Python Pickle
    • Ruby
    • Shell
    • TypeScript
  • Dashboard and Graphs
    • Primary Dashboards
    • Dashboard Library
    • Local Dashboard Integration
    • Worldmap Panel
    • Graphite Dashboard Guide
    • Graphite Graph Menu Reference
    • Other Dashboard Options
  • Alerting Guide
    • Alerting Overview
    • Alerts API
    • Notification Channels API
    • Scheduled Mutes API
    • Using Your Own Alerting
  • Agents Guide
    • The Hosted Graphite Agent
      • Base Metrics
      • System Layout
    • Telegraf
    • K8 Telegraf Daemon
    • OpenTelemetry
    • collectd Agent
    • StatsD Agent
    • Diamond
  • Add-Ons and Integrations Guide
    • AWS CloudWatch
    • Azure Monitor Metrics
    • GCP Metrics
    • Carbon-C-Relay
    • Circle CI
    • Cloudbees
    • Collectd Add Ons
    • GitHub
    • GitLab
    • Heroku
    • Hosted StatsD
    • New Relic
    • Papertrail
    • Pingdom
    • Sentry
    • Sitespeed
    • StatsD Add-on
    • Statuspage
  • Account Management
    • Access Keys
    • Account Diagnostics
    • Account Settings
    • Team Access: Limited Access Groups
    • SAML Authentication
    • Team Access
  • Additional Features
    • Aggregation Rules
    • Data Views
  • API Guides
    • Metrics API
    • Tag API
    • Graphite Render API
    • Render Variables API
    • Dashboard API
    • Annotations and Events API
    • Aggregation Rules API
    • Alerts APIs
  • FAQ
    • General
    • Business
    • Technical
    • Account Metrics and Limiting
    • Customization
    • Troubleshooting
    • Support
    • Changelog
Powered by GitBook
On this page
  • Creating an Annotation
  • Delete a single event
  • Delete an annotation
  • Graphite Events
  • Dashboard Annotations

Was this helpful?

  1. API Guides

Annotations and Events API

PreviousDashboard APINextAggregation Rules API

Last updated 4 months ago

Was this helpful?

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

Created

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://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

OK

Bad Request

Curl example:

curl -X DELETE https://YOUR-API-KEY@api.hostedgraphite.com/api/v1/annotations/events/ \
     -d '{"title": "New Super-duper Feature", "timestamp": 1431607046}'

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

  • 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:

Optional timestamp describing when the event completed. Note: We currently don’t support . As a result, end_time has no actual use in annotations.

Events as per the Graphite project are fully supported. Insertion and rendering of 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:

The dashboard annotations feature works exactly as specified in the . It can be used to query by tags (not graphite targets).

Graphite Events
annotation documentation
Annotations and Events API
Creating an annotation
Delete a single event
Graphite Events
Graphite Composer
Dashboard Annotations
Creating an Annotation
Delete a single event
Graphite Events
Graphite Composer
Dashboard Annotations
region events
Locate annotations in dashboard settings
Configure the annotation query with tags
Visualize annotations