Table of Contents
I have Grafana to thank for introducing me to Mermaid diagrams - one day at work a new Diagram widget appeared and naturally I had to explore further.
What I found amazed me. If you are a fan of diagramming, markdown, and CLI tools - and have not heard of Mermaid, you are in for a treat!
Mostly I find myself making use of the basic flowchart abilities. You can quickly conjure up
something like this in a couple of minutes:
By writing the following:
graph LR; A(something 1) B(something 2) C(something 3) D(something 4) E(something 5) F(something 6) G(something 7) H(something 9) I(something 10) A-->B A-->C A-->D B-->E C-->E C-->F C-->G D-->G F-->H F-->I
Of course you can use slightly more meaningful names, rather than A, B, C etc. You can also define the names as you go, though I’ve started to prefer listing them all out first - it makes future adjustments easier.
graph LR; LB(Loadbalancer)-->AppLogin(Login Service) LB-->AppWeb(Web Service) LB-->AppData(Data Service) AppLogin-->DBUser(User Database) AppWeb-->DBUser AppData-->DBUser
You don’t actually need to provide (Different Names) like that either, if you don’t care about spaces, so this could be cleaner:
graph LR; Loadbalancer --> LoginService Loadbalancer --> WebService Loadbalancer --> DataService LoginService --> UserDatabase WebService --> UserDatabase DataService --> UserDatabase
Flowcharts can also include subgraphs which become very helpful when making larger diagrams. For example, see how the
something flowchart above changes when subgraphs are introduced:
View Source of this page to see the syntax or else this blog post is going to be really long
Oh and you can nest subgraphs too! And change the flow direction:
Depending on your groupings/subgraphs and interactions you might end up with something a bit less messy than that last example. You may also find that moving definitions in and out of subgraphs can really shuffle things around, for what seemed like a subtle change. Here is a reasonably sized, subgraph-filled diagram I’ve created at work:
Still pretty messy towards the Cloud Origins, but pretty useful overall for conveying main traffic flows when explaining how parts of the website were served during our migration from The Datacenters to The Cloud…
It’s even possible for the nodes in a flowchart to be hyperlinks - so they can link off to other useful resources like monitoring or documentation!
Achieved with definitions such as:
click EMEA "https://monitoring.example.com" "view EMEA realtime monitoring"
Bonus points for you if you noticed this already in the Mermaid Diagrams Are Awesome flowchart at the start of this post.
Sequence Diagrams #
Here is a sequence diagram example covering a slice of my day job:
We write some code (MetricsCollector) that frequently pings an API (VendorAPI) to retrieve real-time monitoring data which we then shovel into an internal API (MonitoringSystem) which allows us to use all our favourite internal tools to query, visualize and alert on it (MonitoringSystem again for brevity, AlertingSystem).
I started off thinking the above would seem like a weird abuse of sequence diagrams to those who use them regularly, but a little reading up on them led me to find the following, which I guess explains why it felt like a good weird as I wrote it:
“While there is the assumption that Sequence Diagrams were made for developers, the truth is that a company’s business staff could use such diagrams to communicate how exactly the business presently currently works by illustrating how the different business objects interact.” - Creately
The syntax for my diagram is as follows:
sequenceDiagram; participant VendorAPI participant MetricsCollector participant MonitoringSystem participant osgav participant AlertingSystem Note over VendorAPI,MonitoringSystem: data collection loop 45 seconds MetricsCollector->>VendorAPI: give me last 5mins data MetricsCollector->>MonitoringSystem: send metrics end Note over MonitoringSystem,AlertingSystem: anomaly detection loop 1 minute AlertingSystem->>MonitoringSystem: give me last 10mins data MonitoringSystem->>AlertingSystem: here you go opt rule match AlertingSystem-->>osgav: anomaly detected! end end Note over VendorAPI,MonitoringSystem: data integrity loop 15 minutes MetricsCollector->>MonitoringSystem: give me last 2hrs data opt dataset incomplete MetricsCollector-->>VendorAPI: query for missing data MetricsCollector-->>MonitoringSystem: backfill missing metrics end end Note over MonitoringSystem,AlertingSystem: "monitoring" loop adhocly osgav->>MonitoringSystem: show me the data MonitoringSystem->>osgav: here you go opt osgav-->>AlertingSystem: forge rule updates end end
Gantt Charts #
Mermaid can also render Gantt charts, but they definitely look like the least enjoyable to write. So far I haven’t convinced myself to try. See details here.
Mermaid CLI #
It just gets better: there is even a CLI tool!
This CLI tool takes a mermaid definition file as input and generates svg/png/pdf file as output.
mmdc -i input.mmd -o output.svg -w 1024 -H 768 mmdc -i input.mmd -o output.png mmdc -i input.mmd -o output.png -b '#FFF000' mmdc -i input.mmd -o output.png -b transparent mmdc -i input.mmd -o output.png -t forest
All sorts of possibilities exist due to there being a CLI tool here… for example you could create a more rudimentary version of the Grafana-Mermaid integration.
Instead of elements of a flowchart being tied to a timeseries metric, a script could determine adjustments to the mermaid code (change a solid line to a dashed line or colour a node orange instead of green to represent link degradation for example) and regenerate an
output.png based on this change.
That image could be placed in some
/var/www/public/ folder and is available to relevant people via
https://internal.example.com/network/status.png or… you could load that image in a Grafana text panel of course!
Mermaid Diagrams on Hugo #
How else would I be telling you about them?
Mermaid gets a fleeting mention in this excellent talk from Cloudflare at SREcon'17 (Monitoring Cloudflare’s Planet-Scale Edge Network) covering this kind of usage, in the context of Dashboards as living documentation.
Some info about sequence diagrams:
- Visual Paradigm - What is Sequence Diagram?
- trace modeler - A Quick Introduction to UML Sequence Diagrams
- UML Diagrams - UML Sequence Diagrams
And this is a really cool talk - Running a Power Plant with Grafana - lots of interesting panel development, a few of which are public: