Plugins 〉ACE.SVG
ACE.SVG
React powered SVG Panel Plugin for Grafana
This is an SVG panel plugin for Grafana 10.x+
Why yet another SVG panel plugin?
Yes, I definitely considered naming it YASPP... The existing SVG panel plugins all use the pre-7.0, Angular panel API. I wanted to be able to use all of the features included in the new data API, as well as potential performance improvements from migrating to React. I have also taken a slightly different direction/philosophy from some of the other SVG plugins.
How does it work?
- Users of this plugin are expected to have ready to animate SVG graphics created in an vector design package (See Inkscape, Adobe Illustrator, or a web tool like draw.io).
- Users upload their existing SVG layouts into the plugin, then enable the "Click to Map" functionality, allowing you to easily map arbitrary group, path or text span IDs to named tokens.
- Users then perform additional setup tasks in an init function that gets called each time the SVG panel is loaded.
- Finally, users can access the elements of the SVG using the named tokens from within the render function, called whenever the panel receieves new data.
- User code in either the render or init functions have access to all of the mapped elements, the root SVG document, a ephemeral state store and the DataFrames for the panel.
What are the goals for this project?
- Be the most performant way to visualize arbitrary SVG graphics and animations within Grafana
- Stay out of the way - This plugin will focus on providing simple, obvious tools to reduce the friction of converting your static SVG graphics into data driven visualizations, without limiting your options.
- Stay focused - This plugin will not attempt to be an online graphics editor.
Getting started
- Create a new panel and select ACE.SVG as the visualization
- Paste your SVG source file into the SVG Document tab editor.
- Use the 'Click to Map' functionality in the SVG Mapping tab to map SVG Elements to variables.
- Write code that you want to run once on dashboard load in the User JS Init tab editor.
- Write code that you want to run on when data is received in the User JS Render tab editor.
- Make generous use of the browser JS console and console.log() to explore the features of the plugin and SVG.js
Execution Environment Interfaces
The plugin makes available several interfaces to the SVG document and Grafana in the execution context of the Init and Render functions. Below are details for each one, remember you can always use the browser JS console and console.log() for more detail.
svgmap
svgmap is a JS object where each mapped SVG.js Element is available as a property. Example: If you have an svgid 'rect4524' and you've provided the mapped name bigSquare, you would access the SVG.js methods on that element undersvgmap.bigSquare
. The svgmap is also included asoptions.svgMappings
data
data is the raw object passed in to the panel for rendering by Grafana, it contains the DataFrames with all timeseries data selected by the active queries and time range. This interface is a bit complex and verbose, so we'll be adding helper methods to make common use cases simpler. Grafana DataFrame Docsoptions
options is the raw panel options object manaeged by the dashboard to store panel state. It includes the source code for the svg and functions as well as any mappings or other config data. While you can manually access everything about the panel with this interface, the most common use case is to add properties to it from the Init function for the render function to use later. For instance, if you have a common animation in a panel, you might create a function for setting it up in Init, and attach it to the options object as a property, so that you can use it in the Render function and keep the logic flow clear.svgnode
is a reference to the SVG.js objectcontext
is an initially empty object passed into the init function. The init function may store any context or state that you to preserve between init and renderings. This is not required, but for some advanced use cases - for example, svg generators in the init function - being able to pass data from init to render (and between render invocations) can be useful.
The 'data' object contains both the query definition and the results of the query. In the case of the user initialization function there likely won't be any results (yet), but the query definition should be present. This may be useful for some initial rendering purposes, but caution is advised as the query may be updated (for example while the user is updating the query) so anything done here should likely be done in the update function as well.
Important Notes
- An object's
style
property takes precedence overfill()
. This could be an issue when creating graphics in Inkscape, which uses thestyle
property to assign the fill color. To fix this, you must remove thefill:#FFFFFF;
part under that element'sstyle
.
Learn more
- SVG.js The Core SVG library made available for SVG DOM manipulations.
- Grafana Docs Documentation for users and developers.
- Mozilla Developer Documentation on the SVG standard itself.
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
.h4 . .mb-0 }
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Installing ACE.SVG on Grafana Cloud:
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
For more information, visit the docs on plugin installation.
Installing on a local Grafana:
For local instances, plugins are installed and updated via a simple CLI command. Plugins are not updated automatically, however you will be notified when updates are available right within your Grafana.
1. Install the Panel
Use the grafana-cli tool to install ACE.SVG from the commandline:
grafana-cli plugins install
The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.
Alternatively, you can manually download the .zip file for your architecture below and unpack it into your grafana plugins directory.
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
2. Add the Panel to a Dashboard
Installed panels are available immediately in the Dashboards section in your Grafana main menu, and can be added like any other core panel in Grafana.
To see a list of installed panels, click the Plugins item in the main menu. Both core panels and installed panels will appear.
Change Log
All notable changes to this project will be documented in this file.
0.1.5
- Fix dependabot issues with dependencies
ws
,braces
,fast-loops
,webpack
,path-to-regexp
- Update node version to 22
- Update dependency versions and workflows
- Adds new workflows to bundle stats and update plugin creation
- Update broken badges on main README page
- Add important note about CSS precedence
- Add additional developer instructions
- Move
console.log
into User JS Init Code - Split README into two files: "Grafana marketplace" and "for developers"
- Remove deprecated
<HorizontalGroup>
and<VerticalGroup>
classes, use<Stack>
instead - Remove unused media files
0.1.4
- Resolve
SvgMappings
event error (thanks, @hyunki85!) - Update dependencies and workflows
0.1.3
- Add some additional useful links to the readme
- Improve code quality by adding
readonly
/const
modifiers, access modifiers, and function return types - Replace Monaco code editor with builtin Grafana
CodeEditor
- Simplify and add comments in the init source in the example
0.1.2
- Fix the builtin example
- Update dependency versions
- Update commands in reamde from
yarn
tonpm
- Remove provisioning folder
- Remove devDependency on
emotion
0.1.1
- Fix bad link in readme
- Update dependency versions
- Clean out some old config files
0.1.0
- Update framework for Grafana v10 compatibility