#grafana #script #script-runner #event-handling #events #run #handler

app gdo-runner

Grafana runner for custom event handler scripts

1 unstable release

0.1.0 Aug 18, 2022

#14 in #grafana

MIT/Apache

5MB
20K SLoC

JavaScript 19K SLoC // 0.2% comments Rust 422 SLoC // 0.0% comments Python 45 SLoC

Grafana Do

CI

About

Grafana Do lets you run your own scripts in response to key events within Grafana or its plugins. Scripts have built in access to a rich complement of Grafana APIs.

Team

The team

Technical overview

Technical overview

You can also open assets/grafana-do-overview.excalidraw in Excalidraw and continue working from there.

Development

First, get a copy of the source:

git clone git@github.com:grafana/hackathon-2022-08-grafana-do.git

System Dependencies

  1. First, install rustup and make sure to install rust toolkit 1.63 or later. (latest should work)
  2. Have the WasmEdge library installed installed globally.
  3. Make sure docker is set up and working.

Development

  • cargo build will build the runner, placing output in target directory.
  • cargo check will check lint issues
  • cargo run will build and run the runner

Building docker image

  • docker build .
  • make publish can be used to build a 'multiarch' deployment image suitable for publishing on docker hub.

Using Flakes for System Dependencies and building/running

You might want to use nix and nix flakes to manage dependencies. This eliminates differences between our systems and enables useful shared tools.

The first step is to install nix in the recommended way if you don't already have it. This works on macOS or Linux.

Once installed, to use flakes on macOS:

  • install flakes: nix-env -iA nixpkgs.nixFlakes

  • Modify ~/.config/nix/nix.conf to include the lines:

    experimental-features = nix-command flakes
    keep-derivations = true
    keep-outputs = true
    

With the above steps complete, you can cd into the project and use nix commands to test it out.

  • nix build at the root of the repo will build the entire project to completion, leaving behind result directory containing build products.
  • nix develop will start a shell with useful tools.
  • nix run will run the gdo-runner runner.

Usage

API

  • GET / → tokenless confirmation server is working
  • POST /execute → multipart script posted for execution returns SHA256 of script and runs it async. Requires secret in header.
  • POST /challenge → checks token is ok, without doing anything else

Environment Variables

Currently, there are runtime environment variables:

export APP_KEY="YOUR_SHARED_SECRET"
export APP_ROOT_PATH="/tmp/wasm-scripts"
export APP_USER="your-user@grafana.com"
export APP_ROLE="Admin"
export APP_API_KEY="zjzTah35Tl6bVJfsmg9LCJuIjosdf5ja0="

It's recommended you use a tool like .env or direnv to manage these variables.

Running scripts

See example/README.md for an example of curl commands that exercise the runner.

Dependencies

~23–37MB
~609K SLoC