Grafana data source plugin template

This template is a starting point for building a Data Source Plugin for Grafana.

What are Grafana data source plugins?

Grafana supports a wide range of data sources, including Prometheus, MySQL, and even Datadog. There’s a good chance you can already visualize metrics from the systems you have set up. In some cases, though, you already have an in-house metrics solution that you’d like to add to your Grafana dashboards. Grafana Data Source Plugins enables integrating such solutions with Grafana.

Getting started

Frontend

1. Install dependencies

   yarn run install

2. Build plugin in development mode and run in watch mode

   yarn run dev

3. Build plugin in production mode

   yarn run build

4. Run the tests (using Jest)

   # Runs the tests and watches for changes, requires git init first
   yarn run test
   
   # Exits after running all the tests
   yarn run test:ci

5. Spin up a Grafana instance and run the plugin inside it (using Docker)

   yarn run server

6. Run the E2E tests (using Cypress)

   # Spins up a Grafana instance first that we tests against
   yarn run server
   
   # Starts the tests
   yarn run e2e

7. Run the linter

   yarn run lint
   
   # or
   
   yarn run lint:fix

Distributing your plugin

When distributing a Grafana plugin either within the community or privately the plugin must be signed so the Grafana application can verify its authenticity. This can be done with the @grafana/sign-plugin package.

Note: It's not necessary to sign a plugin during development. The docker development environment that is scaffolded with @grafana/create-plugin caters for running the plugin without a signature.

Initial steps

Before signing a plugin please read the Grafana plugin publishing and signing criteria documentation carefully.

@grafana/create-plugin has added the necessary commands and workflows to make signing and distributing a plugin via the grafana plugins catalog as straightforward as possible.

Before signing a plugin for the first time please consult the Grafana plugin signature levels documentation to understand the differences between the types of signature level.

1. Create a Grafana Cloud account.
2. Make sure that the first part of the plugin ID matches the slug of your Grafana Cloud account.
   • You can find the plugin ID in the plugin.json file inside your plugin directory. For example, if your account slug is acmecorp, you need to prefix the plugin ID with acmecorp-.
3. Create a Grafana Cloud API key with the PluginPublisher role.
4. Keep a record of this API key as it will be required for signing a plugin

Release

To trigger the workflow we need to push a version tag to github. This can be achieved with the following steps:

1. Create a new branch for the release.
2. Update any files needed.
3. Bump version number in the package.json file.
4. Add a new section to the CHANGELOG.md file. This file is published with the plugin and is visible by people viewing our plugin.
5. Once the PR is merged, add a tag to the repo with the same name as the version v#.#.#.
6. Upload the new release to grafana.com to get published.

Learn more

Below you can find source code for existing app plugins and other related documentation.

• Basic data source plugin example
• Plugin.json documentation
• How to sign a plugin?

Provisioning

PreSetup

Get a testing workspace ID and generate an api key with the analyst role.

Base64 encode the key (if not already done so) in the format :<key> where key is preceded by a colon.

Running the Provisioning File

Run the following commands replacing <workspace_id> and <session> with their respective values.

export RRDS_WORKSPACE_ID=<workspace_id>
export RRDS_SESSION_TOKEN=<session> 
docker-compose up

This will set the environment variables needed to correctly spin up the docker instance and auto provision the datasource.