Monitoring / Grafana

Add Checkmk as a Grafana Datasource: Setup and the Field That Breaks It

The official Checkmk datasource plugin for Grafana works well once it is configured right.

Two things get in the way. Its real request-body shape is not documented anywhere you can reach from Grafana's own API docs. And one settings field defaults to a value that silently breaks every graph on a free Checkmk install.

The #1 thing to check if every graph is broken

BE WARNED: the "Edition" setting assumes a commercial edition, even when you point it at a free Checkmk install. With the wrong edition selected, every graph query 404s on an autocomplete call that does not exist on Community builds. The error reads like a helpful hint. It is easy to miss, because the field already shows a selection. It does not look empty or wrong at a glance.

Fix. Open the datasource settings. Set Edition to Community Edition, or whichever matches your install. Save and Test.

If every panel fails identically no matter which host or service it targets, check this field first.

The real panel query shape, since it isn't documented anywhere obvious

This plugin is frontend-only JavaScript with no backend binary. Its request format is not discoverable through Grafana's normal datasource API docs.

Recovering it took reading the plugin's minified source and capturing a real request in a browser network inspector. A panel target looks like this.

{
  "refId": "A",
  "datasource": {"type": "checkmk-cloud-datasource", "uid": "<datasource-uid>"},
  "requestSpec": {
    "site": "monitoring",
    "host_name": "<host>",
    "service": "<service description>",
    "graph_type": "predefined_graph",
    "graph": "<graph-id, resolved separately>",
    "aggregation": "off"
  }
}

graph_type can also be "single_metric". That needs a metric ID instead of a graph ID, resolved through a different autocomplete endpoint than the one below.

Resolving graph IDs: call Checkmk's REST API directly, not Grafana

Graph IDs are not predictable from a service name. They are not portable across hosts either, even for identically named services.

The same "CPU utilization" service resolves to a different internal graph ID depending on whether the check underneath is SNMP or agent-level.

So resolve it per host and service pair, every time, through Checkmk's own REST API. Not through Grafana's datasource proxy.

curl -s -X POST "http://<checkmk-host>/<site>/check_mk/api/1.0/objects/autocomplete/available_graphs" \
  -H "Authorization: Bearer automation <secret>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"value":"","parameters":{"strict":true,"show_independent_of_context":false,
       "context":{"siteopt":{"site":"monitoring"},"host":{"host":"<host>"},
                  "service":{"service":"<service>"}}}}'

BE WARNED: the request body has several traps, and every wrong guess gives a different unhelpful error instead of stating the correct shape. The top-level key is parameters, not params. context nests inside parameters, not alongside value. Host, service and site are each wrapped in their own single-key object, so {"host": {"host": "..."}} and not a bare string.

Set Accept: application/json explicitly. Some HTTP clients do not send it, and without it this Checkmk version returns a bare 406 even when the body is correct.

Building a large dashboard: skip the panel editor, POST the JSON directly

Clicking through Grafana's panel editor once per series is slow and error-prone past a handful of panels.

Build the whole dashboard JSON client-side instead. Every panel, every target, one structure. Then create it in a single call.

POST /api/dashboards/db

Set a fixed "uid" in that payload. Do not let Grafana generate one.

With a fixed UID, re-running the creation script updates the dashboard instead of creating a duplicate.