Creating Grafana Annotations with InfluxDb

Published: August 8, 2016

Tags:

I built a SaaS app called Domain Clamp which monitors domain and SSL certificates and sends you notifications before anything expires. If you've ever been blamed (e.g. by a client) for letting a domain you don't own expire, check it out »

When reviewing historical data in tools such as InfluxDb, it’s typically useful to overlay a timeline of key events. For example, Google Analytics features a simple GUI for adding annotations and New Relic offers an API for marking deployments. In this post we’ll look at creating annotations for your InfluxDb powered Grafana visualizations.

Composition of an annotation

As shown in the official Grafana documentation for annotations with InfluxDb, an annotation is composed of up to 3 pieces of data…

  1. Title
  2. Tags
  3. Text

Grafana hasn’t provided any official recommendation on how to use these three fields (that I can find), but in the screenshot below…

  1. “Deployed v10.2.0” is the “Title”
  2. “Release notes” is the “Text”
  3. “these” “are” “the” “tags” are the “Tags”

Grafana InfluxDb Annotation Screenshot

From my research it seems that…

  1. The title is typically used to provide a heading for the event
  2. The text provides additional information. Linking to release notes is good use case
  3. I’m not sure what tags are meant to be used for. Perhaps to allow filtering of annotations on a dashboard for certain tags, although I haven’t seen that documented anywhere.

Writing to data to InfluxDb

Grafana expects that each of the pieces of data will come from a field not a tag.

The InfluxDb query to create the annotation from the screenshot above looks like this.

curl -X POST "http://localhost:8086/write?db=mydb&precision=s" --data-binary 'events title="Deployed v10.2.0",text="<a href='https://github.com'>Release notes</a>",tags="these,are,the,tags" 1470661200'

As you can see…

Pulling the data into Grafana

The annotation can be pulled into Grafana as follows…

Grafana InfluxDb Add Annotation

Per the Grafana docs, if you only select one field you don’t need to fill out the Column mappings and that field will automatically be pulled in as the title

Limitations

Annotations are created on a per dashboard basis….

Conclusion

When I was first reading on annotations I found that a lot of information was missing from the Grafana annotation docs, so I’m hoping this will help a few people. Feel free to use the comments section below or hit me up on Twitter if you have comments or questions.