Automatically add annotions to Grafana

Hey there!

Today I found out how to add annotations in grafana automatically with a rule from OpenHAB. I didnt find any instructions so I thought I’d share my knowlegde.

What you can do after this tutorial

Add annotations to grafana automatically from a rule via OpenHAB. So you can add an annotation when i.e. the climate control goes on for your power consumption graph or when a device goes offline for your online monitoring graph

What you need

  1. A running OpenHAB instance
  2. A running Grafana instance. It doesn’t matter if it runs on the same host as the OpenHAB instance

How to

  1. Create an API-Key: For that click on “Settings” → “Api Keys” in your Grafana dashboard. Set your API Key to not expire The name of the key doesn’t matter and is only used for naming purposes inside Grafana
  2. Create the rule in OpenHAB:
val String url = "http://api_key:API-KEY@IP:3000/api/annotations"
val String DashboardID = "2"

rule "Add annotation to Grafana if Bettlampe goes offline"
    Item Netzwerk_Bettlampe_Online changed to OFF
    logInfo("Rule triggered", "Rule \"test.rules: Testrule\" started")
    var String json =  '{
        "dashboardId":' + DashboardID + ',
        "time":' + Long::toString(now.millis) + ',
        "text":"Bettlampe offline"
    sendHttpPostRequest(url, "application/json", json)
  1. Exchange your IP address and your API-Key (the upper case “API-KEY”, the lower case stays the same). It should look something like this:

    val String url = "http://api_key:eyJrIXXXXXXXXXXXXXXXXXXXXXXiLCJuIjoib3BlbmhhYiIsImlkIjoxfQ==@"
  2. Exchange your DashboardID and the panelId
    a. You can find the DashboardID by going to your desired dashboard and then “Dashboard settings” (in the upper right) → “JSON Model” and then "id"

    As you can see the ID of my desired dashboard is “2” and since I only have this one dashboard I made it a global variable.
    b. You can find the panelID by clicking on share on the desired panel and then searching in the link for "viewPanel="image
    In this case the panelId is “10”.

Now you can edit the rule as you want to do add annotations as you desire.
You can find more information on whats possible in the Grafana documentation.

Finding mistakes
When you get this message in your log

Fatal transport error: java.util.concurrent.ExecutionException: org.eclipse.jetty.client.HttpResponseException: HTTP protocol violation: Authentication challenge without WWW-Authenticate header

you did something wrong at the authentification. Check your settings there.

The end
Questions/Suggetions/Other ideas?

I hope I was able to help you and give you some ideas whats possible with this!



I am also using annotations to monitor the effectiveness of my blind control on the room temperatures. I create an annoation when a blind rule activates. I also check that my high wind limit switch activates at the correct point by adding an annotation when it triggers on my wind speed chart.

You can toggle the annotations to show or not show on the Grafana charts. Grafana automatically adds a button for each annotation label. See example above. Also, annotations are shown on all charts on the same dashboard.

My example of the code I used in a rule is below:

the variables declared at the top of the rules file:

val String url = "http://admin:<password>@<IP of grafana server>:3000/api/annotations" //Grafana authentication
var String json

Code placed in the rule at point you want an annotation when rule is triggered

    json = '{
        "time":' + Long::toString(now.millis) + ', //time at which annotation is placed
        "tags":["BlindControl"], //Tag/label shown in Grafana chart with button to turn annotation on and off
        "text":"Open - dull" //text to display on mouse over of annotation
    var output = sendHttpPostRequest(url, "application/json", json) //sends annotation request
    logInfo("Blinds",  "Annotation output:  " + output) //logs result of request in openHAB

Thats it for openHAB.

Now the Grafana part:
In Grafana (logged in as admin) goto your Dashboard and select the Dasboard settings option shown on the top row. Then select annotations and add a new annotation query. Give it the same tag name as you used in your openHAB rule. You can have multiple tags if want to show multiple annotations with different tag names on the same dashboard charts.

1 Like

I´m a little bit confused because there´s already a HowTo for Grafana annotation (with two n)

To be honest I didn’t see/find that…