/grafana-plugin-sdk-typescript

Primary LanguageJavaScriptMIT LicenseMIT

Grafana Data Source Backend Framework for Typescript

This framework is for writing a backend datasource in typescript

Support

This SDK is not an officialy supported Grafana Labs project! You can find the officialy supported SDK here. We recommend to read the official guide on how to build your own plugins first.

What is Grafana Data Source Backend Plugin?

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.

For more information about backend plugins, refer to the documentation on Backend plugins.

Getting started

A data source backend plugin consists of both frontend and backend components.

Frontend

  1. Install dependencies
yarn install
  1. Build plugin in development mode or run in watch mode
yarn dev

or

yarn watch
  1. Build plugin in production mode
yarn build

Backend

Why use a backend datasource?

Backend datasources send messages through grafanas backend. This means query responses are routed through grafana's alerting engine, giving your plugin alterting capabilities for free.

Using this framework (migrate a frontend datasource to a backend one)

To make migration of your frontend-only datasource plugin as simple as possible, the following should convert your plugin to a backend datasource

  1. Edit your plugin.json and add the following:
backend: true,
executable: "gpx_<identifier>",
  1. Add the dependency to your package json and install "@grafana/tsbackend": "grafana/grafana-plugin-sdk-typescript"
  2. Create a directory called shared and moves your types.ts file to shared.
  3. In the root of your plugin cp node_modules/@grafana/tsbackend/tsconfig.backend.json . to get the backend typescript compiler configuration for the backend.
  4. Create a directory called backend and then cp node_modules@grafana/tsbackend/skel/*.ts backend/ to copy the skeleton files for the typescript backend.
  5. Edit the files in the backend directory. Change the class names. Import your query, and update the DataService so that the DataRequest is using your specific query type. Edit index.ts and ensure the proper files are renamed and being imported.
  6. Add the following to your package.json under the scripts section
 "backend": "./node_modules/@grafana/tsbackend/bin/grafana-tsbackend gpx_<identifier>_<platform (darwin/windows/linux>)_<architecture arm/amd64>",
 "restart:backend": "kill $(ps -ef | grep gpx_<identifier>_<platform (darwin/windows/linux>)_<architecture arm/amd64> | grep -v grep | awk '{ print $2 }')",
  1. Modify the entry for building the plugin. If desired, you can also add yarn backend to build the backend as well.

Logging

Logging takes places in the grafana log for backend plugins. To log:

import { logger } from '@grafana/tsbackend';

You can then use the following calls for logging:

  • logger.debug
  • logger.error
  • logger.log
  • logger.warn
  • logger.info

Learn more