Creating Grafana Annotations with InfluxDb

Published: August 8, 2016

Tags:

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.

Hi, I'm Max!

I'm a software developer who mainly works in PHP, but also dabbles in Ruby and Go. Technical topics that interest me are monitoring, security and performance.

During the day I solve challenging technical problems at Something Digital where I mainly work with the Magento platform. I also blog about tech, work on open source and hunt for bugs.

I built a tool called Domain Clamp which monitors and alerts about expiring domains and SSL certificates.

If you'd like to get in touch with me the best way is on Twitter.