Grafana app plugin template

This template is a starting point for building an app plugin for Grafana.

What are Grafana app plugins?

App plugins can let you create a custom out-of-the-box monitoring experience by custom pages, nested data sources and panel plugins.

Get started

Backend

1. Update Grafana plugin SDK for Go dependency to the latest minor version:

   go get -u github.com/grafana/grafana-plugin-sdk-go
   go mod tidy

2. Build backend plugin binaries for Linux, Windows and Darwin:

   mage -v

3. List all available Mage targets for additional commands:

   mage -l

Frontend

1. Install dependencies

   bun install

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

   bun run dev

3. Build plugin in production mode

   bun run build

4. Run the tests (using Jest)

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

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

   bun run server

6. Run the E2E tests (using Playwright)

   # Spins up a Grafana instance first that we tests against
   bun run server
   
   # If you wish to start a certain Grafana version. If not specified will use latest by default
   GRAFANA_VERSION=11.3.0 bun run server
   
   # Starts the tests
   bun run e2e

7. Run the linter

   bun run lint
   
   # or
   
   bun 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

Signing a plugin

Using Github actions release workflow

If the plugin is using the github actions supplied with @grafana/create-plugin signing a plugin is included out of the box. The release workflow can prepare everything to make submitting your plugin to Grafana as easy as possible. Before being able to sign the plugin however a secret needs adding to the Github repository.

1. Please navigate to "settings > secrets > actions" within your repo to create secrets.
2. Click "New repository secret"
3. Name the secret "GRAFANA_API_KEY"
4. Paste your Grafana Cloud API key in the Secret field
5. Click "Add secret"

Push a version tag

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

1. Run npm version <major|minor|patch>
2. Run git push origin main --follow-tags

Learn more

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

• Basic app plugin example
• plugin.json documentation
• Sign a plugin

Seed data

When running bun run server Docker compose will also spin up a OpenSearch instance.

Initially run the index setup script:

bun run scripts/setup-opensearch.js

then run

bun run scripts/create-depth-trace.js
bun run scripts/create-large-trace.js

To create some sample trace data. Feel free to tweak these scripts to your local needs.

Install OpenSearch plugin

This should already have been done when launch the grafana docker service. If not:

• Login in as admin, pw admin
• Install OpenSearch plugin, http://localhost:3000/plugins
• Add new data source:
  • URL: http://opensearch:9200
  • View index name at http://localhost:9200/\_cat/indices?v , is most likely going to be ss4o_traces-default-namespace

Open API

We are using a contract first approach for the Go resource endpoints. api.yml is the source of truth, and you can generate client & server code via:

bun run generate-api

Styling with Tailwind CSS

This project uses Tailwind CSS for styling. Note that Tailwind cannot detect dynamically constructed class names, so we use inline style tags for truly dynamic values. For more details, see the Tailwind CSS documentation on dynamic class names.

Packaging and installing the plugin

Run bun run package to create a plugin zip archive.

# Install via the grafana cli
./bin/grafana cli -pluginUrl ../gresearch-grafanaincrementaltraceviewer-app-0.1.0.zip plugins install "gresearch-grafanaincrementaltraceviewer-app"

Afterward you need to start Grafana, if you are using Docker, just restart the container. Once that is done, you need to enable the plugin via the UI.