Using Draw.io diagrams as Grafana Dashboard

Prerequisites:

• Docker or a Grafana instance
• Draw.io (optional)

Note: You could also use the online Draw.io edition.

Step 1: Preparing your Draw.io diagram

Renaming the identifiers

Step 2: Spin up Grafana

For this example, I used Docker. The following command will spin up Grafana, with the correct plugin (agenty-flowcharting-panel) installed.

docker run -d 
  -p 3000:3000 
  --name=grafana 
  -e "GF_INSTALL_PLUGINS=agenty-flowcharting-panel" 
  grafana/grafana

If successful, you can browse to http://localhost:3000 and Grafana should show up.

Login using admin / admin and change the password.

Alternative, using your own Grafana

If you already have Grafana running, with the following command you can install the plugin. Don’t forget to restart Grafana after installing the plugin.

grafana-cli plugins install agenty-flowcharting-panel

Step 3: Add the TestData data source

For this blog we use the test data source in Grafana to create sample data for our graphs.

Assuming you have the Grafana interface open, follow these steps:

1. Click Configuration >> Data Sources
2. Click Add data source
3. Search for TestData
4. Click on TestData
5. Click Save & Test

Step 4: Create sample graphs

Let’s create a Dashboard with a single panel and 7 queries.

1. Click + >> Dashboard
2. Click Add new panel
3. At the left bottom you see a tab called Query (1), it has already a defined query called A
4. Change the query name into api-incoming-requests by clicking on the pencil icon behind the A
5. Set the Scenario, Alias and String Input according to the values in the table as shown below.

6. After each query click on the Duplicate query icon to add the next query.

Your graph should look like this

Step 5: Change the graph into the Draw.io diagram

We need to “export” our diagram to XML, and “import” this into Grafana. Draw.io can be used to create process diagrams and UML diagrams, which can then be exported to Grafana.

In Draw.io (export):

1. Click Extra >> Edit Diagram…. This will show your diagram represented as XML.
2. Select the XML and copy this onto your clipboard

In Grafana (import):

1. On the right, click the tab Panel
2. Expand the Visualizations section
3. Click FlowCharting

4. Expand the FlowChart section that just appeared below the Visualizations section
5. Replace the contents of Source Content with our diagram by pasting the XML. Don’t worry if you diagram is not loading correctly!
6. Enable the following option(s):
   a. Allow draw.io source – this will load the diagram correctly

Step 6: Link Grafana queries to the diagram objects

Now it is time to link our queries to the objects in the diagram. The plugin is using rules for this.

1. Expand the Mapping section in the right tab Panel
2. This will show a default rule called MyRule
3. Expand the default rule MyRule
4. Configure the rule according to the values as show the table API. Each table is a single rule. The screenshot below shows the outcome after the first rule api is configured.

Note: you might see more fields and options, but these are the important once.

5. Scroll up a bit, and collapse the just created rule to make some space
6. Click on the Clone this rule icon to add the next rule.

After adding the first rule named api, you should see a graph if you hover your mouse over the API object.

7. Continue with the next 4 rules (Queue, APP, Database, Pipeline) by repeating step 4, 5 and 6.

Step 7: Setting thresholds and making them visible

For each rule you can set threshold values. If a certain threshold is reached, the state of that rule is changed from [0: Ok] to, for instance, [1: Warning] or [2: Critical]. Based on this state we can modify the appearance of the objects. You can change the text, size of the object, show a little warning icon, or let it old-school blink.

To give you an idea how to set this up, we will add a threshold for the app to warn us when the number of malformed messages in the APP is above 10.

1. Expand the rule app
2. Enable Icon state. This will show a little warning icon near the App object.
3. Enable Invert. This will invert the threshold logic.
4. Set the following thresholds:
   

   Color	Number	Lvl (state)
   Green	Base	0 (Ok)
   Orange	10	1 (Warning)
   Red	25	3 (Critical)

    

5. Under Tooltips, enable Color with state. This will change the color of the graph to match the state (Green, Orange, Red). If you have multiple graphs in a popup, this will make it easy to see for each graph the current state.

Step 8: Trigger the rule and see what happens

Trigger the rule by adding an extra data point to the app-mallformed query.

1. Find the app-mallformed query in the tab called Query at the left bottom
2. And add ,12 to the String input

In the diagram a warning icon is displayed near the App object. If you now hover your mouse over the App object, you will see that the graph change to orange. Go ahead and add an extra data point (,26) to trigger the next threshold level and check that the graph will change to red.

Done

By now you should have a Diagram with 5 objects (arrow included) as shown at the beginning. Hovering over any object should popup the different graphs, a warning icon is shown near the APP, and the APP graph should be colored red.

Extra: More fun with rules

Go back to the app-mallformed rule, and look for the following options:

• Label/Text Mappings
• Link Mappings
• Event/Animation Mappings

These can manipulate the diagram objects for a certain state. Using them is similar to how you set the thresholds in step 6. I’ll briefly explain the options.

Label/Text Mappings
This can be used to change the text label of the object in the diagram if a certain threshold is reached. The configuration below will append the value.

Link Mappings
Based on the threshold values you can set an URL for the object in the diagram. This can be used to link to a more detailed dashboard for the App for instance.

Event/Animation Mappings
To make it more <em>bling</em> <em>bling</em> you can add animation to objects, text labels and arrows in your diagram.

References:

• Grafana plugin page
• Official Flowcharting documentation