Skip to content

Latest commit

 

History

History
189 lines (122 loc) · 6.16 KB

DEVELOPMENT_GUIDE.md

File metadata and controls

189 lines (122 loc) · 6.16 KB
Raw

Development Guide

Environment

To get a development environment up and running, first ensure the following are installed:

  1. go
  2. mage
  3. yarn
  4. docker

Then run the following in different terminals:

  1. Build the front-end and listen for javascript changes:
yarn dev
  1. Build the back-end, inject it into a docker image, and run it alongside a Haxall server:
mage -v && docker-compose -f docker-compose_dev.yaml up

Usage

Create a new data source and select "Haystack". If no Docker configuration has been edited, the Haystack API is available at http://haxall:8080/api/, with the username su and password su. Click "Save and Test" and make sure that it is working.

Create a new dashboard and panel, and use this axon query to test the connection:

[{ts: now()-1hr, v0: 0}, {ts: now(), v0: 10}].toGrid

Note that if your grid's first column is a date-time you can use it with the timeseries chart. Otherwise, nearly every Axon query can be visualized using the table view.

Release

To trigger a new release of the plugin, we need to push a version tag to github. This can be achieved with the following steps:

  1. Fill out changelog and merge
  2. Run npm version <major|minor|patch>
  3. Run git push origin main --follow-tags
  4. Navigate to the GitHub releases page, and follow the instructions in the new draft release.
  5. Before submitting the plugin in Grafana Cloud, edit the release and make it public.
  6. Submit the plugin

Below is the original readme generated by Grafana

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

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

    yarn install

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

    yarn dev

  3. Build plugin in production mode

    yarn build

  4. Run the tests (using Jest)

    # Runs the tests and watches for changes, requires git init first
yarn test

# Exists after running all the tests
yarn test:ci

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

    yarn server

  6. Run the E2E tests (using Cypress)

    # Spin up a Grafana instance first that we tests against
yarn server

# Start the tests
yarn e2e

  7. Run the linter

    yarn lint

# or

yarn 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.