Charts of Checkmk BI aggregations for dashboards: pie, rings, treemap, tree, groups (MKP for Checkmk 2.4 and 2.5)
  • Python 52.8%
  • HTML 46.9%
  • Dockerfile 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Dawid Ciepiela 3ec70460c7
All checks were successful
CI / unit (push) Successful in 1m51s
CI / integration (Checkmk 2.4) (push) Successful in 5m2s
CI / integration (Checkmk 2.5) (push) Successful in 5m1s
CI / integration (update 2.4 to 2.5) (push) Successful in 7m44s
CI / release (push) Successful in 12s
Merge pull request 'test(integration): the sankey's leaves are its hosts' (#10) from fix-sankey-test into main
Reviewed-on: #10
2026-11-20 09:01:45 +00:00
.forgejo/workflows build: the project as pyproject.toml, the build command build-mkp in scripts/ 2026-11-19 21:42:57 +01:00
docs fix(view): treemap with its layered fills again, the BI order below the aggregations 2026-11-19 21:39:15 +01:00
scripts build: the project as pyproject.toml, the build command build-mkp in scripts/ 2026-11-19 21:42:57 +01:00
src fix(view): treemap with its layered fills again, the BI order below the aggregations 2026-11-19 21:39:15 +01:00
tests test(integration): the sankey's leaves are its hosts 2026-11-20 09:46:53 +01:00
tools feat(view): sankey, problems only, patterns, change marks; clearer rings, treemap and tree 2026-11-19 21:05:32 +01:00
.gitattributes Add bi_pie MKP: BI aggregation state pie for Checkmk 2.4 and 2.5 2026-11-19 09:58:23 +01:00
.gitignore build: the project as pyproject.toml, the build command build-mkp in scripts/ 2026-11-19 21:42:57 +01:00
CHANGELOG.md chore(release): 0.2.0 2026-11-19 21:38:31 +00:00
LICENSE Add bi_pie MKP: BI aggregation state pie for Checkmk 2.4 and 2.5 2026-11-19 09:58:23 +01:00
package-lock.json feat(view)!: charts drawn with ECharts, five views besides the pie 2026-11-19 14:18:12 +01:00
package.json build: the project as pyproject.toml, the build command build-mkp in scripts/ 2026-11-19 21:42:57 +01:00
pyproject.toml chore(release): 0.2.0 2026-11-19 21:38:31 +00:00
README.md chore(release): 0.2.0 2026-11-19 21:38:31 +00:00
renovate.json ci: Forgejo pipeline, integration tests on sites from Checkmk's packages 2026-11-19 12:28:55 +01:00

bi_charts: charts of Checkmk BI aggregations

A dashboard element with charts of Checkmk BI aggregations: their states as a pie or as tiles, the BI trees as rings, a treemap, a tree of nodes or flows, the states per group as donuts or bars, and the hosts and services that drag the most aggregations down, with a list of the aggregations that are not OK. Checkmk has no such charts for BI and no way to add custom widget types in 2.5, so this package embeds a static page instead. It draws with Apache ECharts, which the package includes.

The pie with sample data

The rings with sample data

The treemap with sample data

The tree, problems only, with sample data

The flows, problems only, with sample data

Donuts and bars per group with sample data

Tiles and impact with sample data

Hover details with sample data

All rendered from the page with sample data by tools/screenshots.py, not taken from a live site.

Requirements

  • Checkmk 2.4.0 or 2.5.0, any edition: every version Checkmk maintains (2.3 left maintenance on 2026-10-29). CI checks this every week against Checkmk's list of releases and fails once a new version is out and not yet tested.
  • Viewers need access to BI. The shipped dashboard is a packaged one; with Checkmk's default permissions every role may see it.

Install

As the site user:

mkp add bi_charts-0.2.0.mkp
mkp enable bi_charts 0.2.0

The package then provides:

  • the dashboard BI aggregation states (dashboard.py?name=bi_charts)
  • the page local/bi_charts/index.html, for use in your own dashboards

Use it in your own dashboards

Add a custom URL element (2.4) or an Embed URL widget (2.5) with a site-relative URL. Checkmk's documentation lists them among the built-in elements of a dashboard: Custom URL in 2.4, Embed URL in 2.5 (the current documentation; Checkmk publishes no separate 2.5 address).

local/bi_charts/index.html?group=WebApp&title=Web%20applications
local/bi_charts/index.html?view=rings&depth=4&name=Payment%20API
local/bi_charts/index.html?view=bars&group=WebApp&group=Storage&group=Network
Parameter Meaning
view pie (default), rings, treemap, tree, groups, bars, tiles, impact or sankey, see below
group BI aggregation group to include, repeatable; the groups of groups and bars
name Aggregation title to include, repeatable
by groups, bars: group (default when group is given) or pack (BI pack, otherwise)
depth rings, treemap, tree, sankey: levels of rules shown, default 3
problems=1 rings, treemap, tree, sankey: only the paths down to what is not OK
max Views of the trees: most aggregations to load, default 40
top impact: most hosts and services shown, default 15
title Heading above the chart
refresh Reload interval in seconds, default 60, 0 disables
theme dark or light; default: the Checkmk theme of the embedding page
colors Other state colors, e.g. ok:2e7d32,crit:c62828 (ok, warn, crit, unknown, pending)
muted=0 OK in full color; by default it is paler than the problem states
patterns=1 A pattern per problem state besides its color: stripes for WARN and CRIT (each its own way), dots for UNKNOWN
labels=0 No names on the chart
legend=0 Hide the legend
list=0 Hide the list of non-OK aggregations
animation=0 No animation
debug=1 Show the raw REST API response

Clicking a state (a slice, a donut's or bar's segment, a legend row) narrows the list to it; in groups and bars also to that group. Each entry of the list links to the aggregation's BI view.

Views

View Shows Best for
pie One slice per state, its name and count along the ring where they fit, the number of aggregations in the middle A small element, any number of aggregations
rings The BI trees as rings, hosts and services as pills around them Following a problem from an aggregation down to a service
treemap The BI trees as nested rectangles, sized by hosts and services; a click zooms in Many aggregations at once
tree The BI trees as a tree of nodes, folded below depth; a click opens or folds a node Reading the structure of a few aggregations
groups One donut per group, its OK share in the middle Comparing groups at a glance
bars One stacked bar per group, a segment per state Comparing groups by the number of aggregations
tiles One hexagon per aggregation, the worst first, its name inside Many aggregations at a glance, on a wall screen
impact One bar per host or service that is not OK, as long as the aggregations it is part of, a segment per state of those What to fix first
sankey The BI trees as flows from the aggregations through their rules to their hosts; a host shared by several aggregations is one node Seeing what aggregations share

Rings: the innermost ring holds the aggregations, in the same order as the pie. Each further ring, up to depth, is the next level of rules: the rules an aggregation is built from and the rules those call (also across BI packs). Every segment's angle is its share of the hosts and services. The hosts and services themselves are pills in a thin band around the rings, however deep they sit in the tree, so the band shows every problem even when the rings stop early. A segment wide enough carries its name: straight along the radius in a narrow segment, bent along the ring in a wide one, and never upside down. A name is left out where it would be cut to fewer than eight characters (six when bent), so how many names show depends on the element's size. Hovering a segment keeps its path to the aggregation in full color. Where the band has too little room (less than six pixels a pill), the hosts and services next to each other below the same rule that share a state are one pill, and its details name them. A rule's hosts and services that sit higher up than the deepest ring leave its outer rings empty.

Names in the trees: a rule named after its parent plus a word (Web Shop Frontend below Web Shop) shows only that word in the rings, the treemap, the tree and the flows; the details give the whole name. The treemap and the flows put the worst aggregations first, as the tiles do.

Problems only (problems=1): the views of the trees leave out what is OK throughout and keep the paths down to every host or service that is not OK, also in an aggregation that is OK itself (a rule that tolerates a failed member). Below the chart the page says how many aggregations it left out. The details of a node still count all the hosts and services below it.

Sankey: a column of aggregations, one per level of rules up to depth, and the hosts last. Each host or service flows from the rule above it to its host, so a host's node is as high as its services in all the aggregations shown, and a host in several aggregations (a core switch, a storage system) gathers flows from all of them. A flow has the color of the worst state in it. Rules below depth are left out; their hosts hang from the rule above. Many aggregations make a long column of hosts: narrow the filter or use problems=1.

Changes: an aggregation whose state changed while the page is open is marked for ten minutes: in bold with since and the time in the list (lit up once when it happens), outlined among the tiles, and with the time in its details. The page remembers nothing between visits, so the first load marks nothing.

Tiles: need only the states, not the trees, so they work for any number of aggregations. A tile also says when its aggregation is acknowledged or in downtime; clicking it shows its state below the chart.

Impact: walks the trees for the hosts and services that are not OK, and ranks them by how many of their aggregations are not OK, then by how many aggregations they are part of. A host or service shared by many aggregations (a core switch, a storage system) comes first. The dot before a name is its own state; the segments are the states of its aggregations, and clicking one narrows the list to those. top sets the number of rows. Being part of an aggregation that is not OK does not prove it is the cause: a rule may tolerate one failed member.

Groups and bars: the state endpoint does not say which group an aggregation belongs to, so by=group asks once per group given, and by=pack groups by the BI pack of each aggregation's top rule, which needs the trees (as the views of the trees, up to max).

Loading the trees takes one request per aggregation. A refresh loads a tree again only when its aggregation's answer from the state endpoint changed (which names the nodes that have a problem) or the tree is ten minutes old, so that a changed BI configuration shows within ten minutes. Above max aggregations the page shows the pie and says so, instead of drawing a partial set of trees.

Hover details and legend

Hovering, or tapping on a touch screen, shows a details box next to the pointer:

  • State (slice, legend row): the state's count and share, and the aggregations in that state with their acknowledged / downtime flags (the first eight, then a count of the rest).
  • Node of a tree (rings, treemap, tree, sankey): the path down to the node, its state and flags, whether it is a rule (with BI pack and rule ID), a host or a service, and how many hosts and services sit below it per state. Clicking it keeps its path on display below the chart.
  • Group (donut, bar): the group's aggregations per state.
  • Tile: the aggregation's state and flags.
  • Impact bar: the host's or service's state, and its aggregations per state (the first eight, worst first).
  • Host of the flows: its state, its hosts and services per state, the aggregations it is in, and its hosts and services, the worst first.

Hovering a legend row fades everything of another state.

The legend lists each state's aggregation count and share, the share also as a bar. In the views of the trees it adds a column with the hosts and services per state across all loaded trees.

OK is drawn paler than the problem states, and small gaps separate the slices and segments, so that problems stand out (muted=0 turns this off). For screen readers the chart's description says the view and the states of the aggregations.

How it works

The page calls GET /api/1.0/domain-types/bi_aggregation/actions/aggregation_state/invoke with the viewer's GUI session, so every user sees only the aggregations they are permitted to see. No data is stored and no automation user is needed.

That endpoint only reports the nodes that have a problem, so the views of the trees also call ajax_fetch_aggregation_data.py, the GUI endpoint behind Checkmk's own BI visualization, once per aggregation. It is not a public API; it is the same in the 2.4 and 2.5 sources.

One package covers both versions because it avoids version-specific code:

Part Content Why it works on 2.4 and 2.5
web htdocs/bi_charts/: the page, ECharts and its licenses Both serve ~/local/share/check_mk/web/htdocs at /<site>/check_mk/local/
gui dashboard/bi_charts Packaged dashboard in the 2.4 format, which 2.5 converts when loading

Dashboard filters do not reach the page, because the embed element does not pass them on. Put the filter into the URL instead.

Known limitations

  • Duplicate titles: Checkmk's state endpoint keys aggregations by title, so two aggregations with the same title count as one.
  • Sizes: the rings, the treemap and the groups' charts weigh aggregations differently: the rings and the treemap by hosts and services, the pie and the groups by aggregations.
  • Load: every open widget asks once per refresh, and each request makes Checkmk compute all matching aggregations; the views of the trees add one request per aggregation whose state changed (and per aggregation every ten minutes), by=group one per group. Raise refresh or narrow the filter on large setups.
  • Internals: the tree endpoint, the packaged dashboard format and the local htdocs path are not public interfaces. version.usable_until is therefore set to 2.6.0; they were only checked for 2.4 and 2.5.
  • Touch devices: a tap shows the details, and on a state also narrows the list; fading by a legend row needs a pointer.
  • When a request fails, the page shows the error and removes the chart, so that outdated data is never mistaken for the current state.

Tests

npm ci                             # the chart library, which the MKP ships
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[test]'           # the project, with build-mkp and the test tools
playwright install chromium        # or: pytest --browser-channel chrome

python3 -m pytest                  # unit tests, a few seconds
python3 -m pytest tests/integration   # real Checkmk 2.4 and 2.5 in Docker
Suite What it checks Needs
tests/unit/test_package.py package sources and the built MKP nothing
tests/unit/test_page.py every view in a real browser, against a stand-in for the Checkmk endpoints a browser, npm ci
tests/integration/test_checkmk.py install, both endpoints with a session cookie, the dashboard and the page in a browser, on 2.4 and on 2.5 Docker
tests/integration/test_update.py the same site updated from 2.4 to 2.5 Docker

The integration tests install Checkmk from its own packages: the newest patch release of 2.4 (Raw edition) and of 2.5 (Community edition), as listed in stable_downloads.json, for Debian 12. Each package is checked against the SHA-256 given there and kept in ~/.cache/bi-charts (BI_CHARTS_CACHE). Both go into one Docker image (tests/integration/image/Dockerfile), built on the first run (about 600 MB of downloads, several minutes) and again only for a new patch release. Every test module creates its sites in containers of that image; the update test runs omd update in the container of the 2.4 site, as on a server. BI_CHARTS_PACKAGE_2_4 and BI_CHARTS_PACKAGE_2_5 name a package file to use instead, e.g. an older patch release.

CI and releases

.forgejo/workflows/ci.yml runs on every push to main, every pull request, every tag and every Monday, so that a new Checkmk patch release is tested before anyone updates to it:

Job What it does
unit the unit tests, and the MKP, kept as the run's artifact for 14 days
integration (Checkmk 2.4) test_checkmk.py on a 2.4 site
integration (Checkmk 2.5) test_checkmk.py on a 2.5 site
integration (update 2.4 to 2.5) test_update.py
release for a tag only, once all of the above passed: the MKP as a release

Each integration job builds an image with only its versions (BI_CHARTS_VERSIONS, default 2.4 2.5); a new Checkmk version is one more entry in the matrix.

Commits follow Conventional Commits. The release bot tags the releases due from them (tool.commitizen in pyproject.toml), writing the version into pyproject.toml (the MKP's too) and the install commands above. The tag runs the whole pipeline, and its release job publishes the MKP with its SHA-256 as a release. The upload to the Checkmk Exchange stays by hand: it has no API, and Checkmk reviews every version. Renovate keeps the test tools in pyproject.toml and ECharts in package-lock.json up to date.

Verification status

Checked against the Checkmk 2.4 and 2.5 sources:

  • session cookies are a documented authentication scheme of the REST API
  • both endpoints return the fields the page reads
  • both versions serve the local htdocs directory and load packaged dashboards from the same directory; 2.5 converts the 2.4 dashboard format when loading
  • the archive is accepted by Checkmk's own MKP manifest parser (2.5)

Checked by the unit tests: the page's behavior in a browser, against a stand-in that answers like those sources.

Checked by the integration tests, on sites installed from Checkmk's packages (2.4.0p41 Raw and 2.5.0p20 Community when this was written; CI tests the newest patch releases every week): the installation, both endpoints with a session cookie, the packaged dashboard, the page in a browser, and the update of a site with the package from 2.4 to 2.5.

Build

npm ci               # ECharts, in the version package-lock.json pins
pip install -e .     # the project: the command build-mkp (scripts/build_mkp.py)
build-mkp            # writes dist/bi_charts-<version>.mkp, no Checkmk site needed

python3 scripts/build_mkp.py does the same without installing the project. The project is installed editable, so that build-mkp reads src/ and node_modules/ of the checkout. The version is project.version in pyproject.toml; build-mkp --version prints it.

The build is reproducible: identical sources give a byte-identical archive.

License

GPL-2.0-or-later, see LICENSE (the text of version 2).

The package includes Apache ECharts under the Apache License 2.0, and zrender, which ECharts bundles, under the BSD 3-Clause license; their license texts and notice ship beside the page (LICENSE-echarts.txt, NOTICE-echarts.txt, LICENSE-zrender.txt). The Apache License 2.0 is compatible with version 3 of the GPL, not with version 2 alone, which is why the package is GPL-2.0-or-later.