Altinity Grafana Plugin for ClickHouse: Ready for Grafana 10 and Beyond
Note: Big shout-out to Eugene Klimov for the information contained in this article.
The Altinity Grafana Plugin for ClickHouse is the oldest and most popular Grafana plugin for ClickHouse databases. Users have downloaded it over 15M times and constructed countless dashboards since 2017. We’re delighted to announce that version 3.0.0 of the plugin has a React front-end and updated back-end SDK version, so it fully supports Grafana 10.
The Altinity Plugin is a community plugin, which means that it’s contributed to Grafana and available to all users. The Altinity Plugin is signed and appears on the Grafana labs plugins page where it is available for installation. Altinity has maintained the plugin since 2019. We use it in Altinity.Cloud and recommend it for our self-managed users as well.
The rest of this article tells you how to get the new plugin and reviews our roadmap. We start with a quick review of how the Altinity Plugin arose in the first place.
History of the Altinity Plugin (or: Why Vertamedia is in the name)
The Altinity Plugin started out in a completely different company. Roman Khavronenko (a co-founder of VictoriaMetrics) wrote it while working at Vertamedia (now Adtelligent) in 2017. He maintained it for the first couple of years, in which time the plugin became quite popular. Roman moved on to other projects in 2019 but thoughtfully transferred maintenance to Altinity. Eugene Klimov is the primary engineer and has now made the majority of commits on the project.
Since becoming maintainers we have made around 30 releases. The latest release, version 3.0.0, includes a full rewrite of the original AngularJS front-end code to React. This enables the plugin to run without limitations on Grafana 10 and future versions.
In 2022 we renamed the plugin from Vertamedia to Altinity at the request of Grafana Labs. The project code now lives in the Altinity GitHub repo. The plugin still keeps the Vertamedia name internally, because that cannot be changed. This seems appropriate, because Vertamedia were the original authors.
How to install the Altinity Grafana plugin 3.0.0
There are multiple ways to install the Altinity Plugin for ClickHouse.
Installation from the command line
Follow Grafana Labs installation instructions to install Grafana locally, then use the grafana-cli tool to add the Altinity Plugin. As noted above the plugin tag harks back to Vertamedia origins. Sample commands are shown below for Ubuntu.
sudo -u grafana grafana-cli plugins install vertamedia-clickhouse-datasource
sudo service grafana-server restart
It’s a good idea to double check the installed version of the plugin to ensure you got the right version. The latest version is 3.0.0. It will install automatically on Grafana version 10.0.3 or greater.
$ sudo -u grafana grafana-cli plugins ls
installed plugins:
vertamedia-clickhouse-datasource @ 3.0.0
Installation from Grafana Administration page
You can install the Altinity Plugin directly from the Grafana server administrative UI. Login to Grafana with the admin account and navigate to the Connections panel. Type “Altinity” to locate the plugin, and click on the name.
Grafana will show the plugin description. Press the Install button to complete installation.
Once installation is complete, the Install button will flip to Uninstall and an Add new data source button will appear. Press the button to create your first ClickHouse data source. Here is a typical example.
Fill in the URL for your server, add credentials (if necessary), check the TLS box (if necessary) and then press the Save & test button at the bottom of the screen. You should see a message like the following if everything is right.
You are now ready to build dashboards. Press the helpful building a dashboard link to get started. Grafana has a nice wizard that drops you straight into dashboard development.
From here on out, check out the Altinity Plugin docs posted on the Grafana Labs site to see all the features available to you.
Upgrading from older Grafana versions
If you are running an older Grafana version and try to install the Altinity Grafana plugin you’ll see a message like the following that limits you to Version 2.5.4.
This is the latest compatible version for Grafana versions prior to 10.0.3. To use the new Altinity Plugin you’ll need to upgrade to Grafana 10.0.3 or later. Here’s how to do it from the command line on Ubuntu.
sudo apt update
sudo apt install grafana
Note: For older Ubuntu versions you may need to use the Grafana Labs repo instead of the default Ubuntu apt repos. Check the Grafana installation docs for details.
Go to the Connections page and select the Altinity Plugin. You’ll see a message like the following. Grafana recognizes that the plugin should be upgraded to the new React-based front-end protocol.
Upgrade the plugin by pressing the Update button at the top of the page. This will now install the version 3.0.0 Altinity Plugin. If you install from the UI you do not need to restart Grafana. Just refresh the screen to see details of the new plugin.
React rewrite – what did we do?
The plugin rewrite to React started in 2023 and released in January 2024. It was the main feature of version 3.0.0. Here are a few details if you are interested in what we did.
- We rewrote the plugin front-end code to use React. Our main goal was to provide a drop-in replacement of the 2.5.4 plugin so that existing dashboards can upgrade without changes.
- In addition, we updated the plugin back-end code to use the latest version of the Grafana Golang SDK.
- We used unit tests of our markup/query engine to ensure compatibility. So far we have seen minimal problems.
- During the rewrite we found and pushed to upstream a fix for inconsistent behavior of the Grafana core code responsible for the routes section in the plugin JSON descriptor. You can see the details in https://github.com/grafana/grafana/pull/80858.
We have done our best to ensure that migration should be seamless for all users of Altinity Plugin 2.5.4 and before. If you notice problems or have other feedback, please log them as issues in GitHub (https://github.com/Altinity/clickhouse-grafana/issues).
Roadmap for Version 3.1.0
Now that the React rewrite is done, we’re working on new features for the next plugin version 3.1.0. The roadmap is published here on the GitHub project. Features include better support for Grafana Cloud, some cleanups left over from the migration, and a number of PRs submitted by users.
We welcome pull requests, so if you have additional ideas, feel free to submit them. We recommend opening an issue first to discuss the implementation. This will save you time. (And us too. ;))
Conclusion
Altinity Grafana Plugin for ClickHouse version 3.0.0 is now fully up-to-date with the Grafana protocol for both the front-end and back-end code. The rewrite from version 2.5.4 eliminates the warning messages users saw on newer versions of Grafana. More importantly, it allows us to continue our work to maintain and improve the Altinity Grafana plugin for many years to come. We have an active roadmap of improvements and will release version 3.1.0 later this year.
Stay tuned for more articles on the Altinity Grafana plugin in the near future. If you would like to contact us directly, feel free to join our Slack Workspace or arrange a direct meeting with the Altinity team. We look forward to hearing from you!