SystemLink Grafana Plugins

Grafana plugins for visualizing data from SystemLink Enterprise.

Description

This project contains a set of data sources and panel plugins bundled as an app plugin, scaffolded using the Grafana Plugin Tools.

Data sources

• Data frames
• Notebooks
• Systems
• Tags
• Assets

Panels

• Plotly.js chart

Contributing

If you're at NI, request to be granted access to the repo. Outside contributors can use a fork & pull workflow.

Getting started

If you're on Windows, you'll need to first set up WSL. Building requires Node.js + npm (18.x is the node version used in build pipelines), and Docker is used to run the Grafana server in a container for development.

After cloning the repo, npm install to fetch dependencies and then npm run start to build in development mode. This command does two things:

1. Starts a process that watches for changes to the source code and automatically rebuilds.
2. Starts up Grafana in a container with the ./dist directory created by the build process mounted. After a brief startup, you should now be able to access the Grafana UI at http://localhost:3000.

Alternatively, if you use VS Code as your editor, this repo contains a launch configuration that runs the steps above and then attaches to an instance of Chrome for debugging. See Debugging in Visual Studio Code for more information.

For panel plugins, there's no extra configuration needed - it will automatically show up in the list of available visualizations.

Data source configuration

For data source plugins, some manual configuration is required to have it connect to a SystemLink service running in the cloud.

1. Navigate to the data sources configuration page (/datasources). You can get there by clicking the gear icon in the sidebar.
2. Select Add data source. Search for the plugin in the list and click on it to enter the data source settings view.
3. Fill in the URL field with the API URL of the Stratus environment you want to use (e.g. https://test-api.lifecyclesolutions.ni.com).
4. For authentication, click the Add header button and add a custom header with the name x-ni-api-key and value set to an API key for the SLE instance.
5. Click Save & test. You should see Success pop up if the data source was configured correctly and the API key grants the necessary privileges.

You should now be able to use the data source when building a dashboard or in the Explore mode. Navigating to Explore is the easiest way to begin testing the plugin.

Testing

If you followed the steps above, a live reload script was injected into the Grafana frontend. Any time the plugin rebuilds, the page will automatically refresh and load the new bundle.

Run npm run test to launch the unit tests in watch mode.

Run npm run e2e to run the integration tests.

Submitting changes

Once you're ready to submit changes to a plugin, all you need to do is open a pull request on GitHub to merge your branch. Don't forget to resolve any lint errors (npm run lint:fix) and ensure that the tests are passing locally.

The repo uses semantic-release and a GitHub workflow to automate the versioning and release process. For this to work, commits to main need to follow a specific message format.

Commit message format

<type>(<scope>): <short summary>
  │       │             │
  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
  │       │
  │       └─⫸ Commit Scope: If your change applies to a single plugin, put its short name
  │                          as the scope (e.g. tag, notebook, system).
  │
  └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|test

The <type> and <summary> fields are mandatory, the (<scope>) field is optional.

<type> must be one of the following:

• build: Changes that affect the build system or external dependencies
• ci: Changes to our CI configuration files and scripts
• docs: Documentation only changes
• feat: A new feature
• fix: A bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• test: Adding missing tests or correcting existing tests
• chore Changes that don't fit into the above categories

For example, if you're making a bug fix to the Data frame plugin, your PR title (and therefore the commit message when merging into main) would be something like:

fix(data-frame): prevent crash when user hits their head on the keyboard

WSL setup

The plugin tools provided by Grafana do not currently support Windows. However, you can still set up the plugin and run commands inside a WSL environment.

1. Enable WSL. If you installed Docker Desktop, it's likely already enabled. Run wsl --update to make sure it's up to date.
2. If you don't have a distribution installed, run wsl --install -d ubuntu to install Ubuntu. Note that your distro needs to be on WSL 2 for Docker to work.
3. Open Docker Desktop. Go to Settings > Resources > WSL Integration and Enable integration with additional distros.
4. Open a shell in your Linux environment. Windows Terminal is recommended for seamlessly managing multiple command lines.
5. Install Node.js.

You can now follow the setup steps. Make sure that you're running the commands in your Linux environment. The WSL extension for Visual Studio Code is recommended to simplify development.

Creating a new plugin

To create a new data source, run npm run generate in the root directory and follow the instructions.

Helpful links

• Grafana plugin developer's guide