Plugins 〉SimpleJson

Grafana Labs

Sign up to receive occasional product news and updates:

Data Source


  • Overview
  • Installation
  • Related content

Simple JSON Datasource - a generic backend datasource

More documentation about datasource plugins can be found in the Docs.

This also serves as a living example implementation of a datasource.

Your backend needs to implement 4 urls:

  • / should return 200 ok. Used for "Test connection" on the datasource config page.
  • /search used by the find metric options on the query tab in panels.
  • /query should return metrics based on input.
  • /annotations should return annotations.

Those two urls are optional:

  • /tag-keys should return tag keys for ad hoc filters.
  • /tag-values should return tag values for ad hoc filters.


To install this plugin using the grafana-cli tool:

sudo grafana-cli plugins install grafana-simple-json-datasource
sudo service grafana-server restart

See here for more information.

Example backend implementations

Query API

Example timeserie request

  "panelId": 1,
  "range": {
    "from": "2016-10-31T06:33:44.866Z",
    "to": "2016-10-31T12:33:44.866Z",
    "raw": {
      "from": "now-6h",
      "to": "now"
  "rangeRaw": {
    "from": "now-6h",
    "to": "now"
  "interval": "30s",
  "intervalMs": 30000,
  "targets": [
     { "target": "upper_50", "refId": "A", "type": "timeserie" },
     { "target": "upper_75", "refId": "B", "type": "timeserie" }
  "adhocFilters": [{
    "key": "City",
    "operator": "=",
    "value": "Berlin"
  "format": "json",
  "maxDataPoints": 550

Example timeserie response

    "target":"upper_75", // The field being queried for
      [622,1450754160000],  // Metric value as a float , unixtimestamp in milliseconds

If the metric selected is "type": "table", an example table response:


Annotation API

The annotation request from the Simple JSON Datasource is a POST request to the /annotations endpoint in your datasource. The JSON request body looks like this:

  "range": {
    "from": "2016-04-15T13:44:39.070Z",
    "to": "2016-04-15T14:44:39.070Z"
  "rangeRaw": {
    "from": "now-1h",
    "to": "now"
  "annotation": {
    "name": "deploy",
    "datasource": "Simple JSON Datasource",
    "iconColor": "rgba(255, 96, 96, 1)",
    "enable": true,
    "query": "#deploy"

Grafana expects a response containing an array of annotation objects in the following format:

    annotation: annotation, // The original annotation sent from Grafana.
    time: time, // Time since UNIX Epoch in milliseconds. (required)
    title: title, // The title for the annotation tooltip. (required)
    tags: tags, // Tags for the annotation. (optional)
    text: text // Text for the annotation. (optional)

Note: If the datasource is configured to connect directly to the backend, you also need to implement an OPTIONS endpoint at /annotations that responds with the correct CORS headers:

Access-Control-Allow-Headers:accept, content-type

Search API

Example request

{ target: 'upper_50' }

The search api can either return an array or map.

Example array response


Example map response

[ { "text" :"upper_25", "value": 1}, { "text" :"upper_75", "value": 2} ]

Tag Keys API

Example request

{ }

The tag keys api returns:


Tag Values API

Example request

{"key": "City"}

The tag values api returns:

    {'text': 'Eins!'},
    {'text': 'Zwei'},
    {'text': 'Drei!'}

Dev setup

This plugin requires node 6.10.0

npm install -g yarn
yarn install
npm run build



  • Fix for query editor to be compatible with Grafana 7+ (broke due to change in Grafana).


  • Support for adhoc filters:
    • added tag-keys + tag-values api
    • added adHocFilters parameter to query body


  • Fix for dropdowns in query editor to allow writing template variables (broke due to change in Grafana).


  • Adds support for With Credentials (sends grafana cookies with request) when using Direct mode
  • Fix for the typeahead component for metrics dropdown (/search endpoint).


  • Adds support for basic authentication


  • Add support returning sets in the search endpoint


  • Allow nested templates in find metric query. #23


  • Dont execute hidden queries
  • Template support for metrics queries
  • Template support for annotation queries

If using Grafana 2.6

NOTE! for grafana 2.6 please use this version

Copy the data source you want to /public/app/plugins/datasource/. Then restart grafana-server. The new data source should now be available in the data source type dropdown in the Add Data Source View.

Installing SimpleJson on Grafana Cloud:

For more information, visit the docs on plugin installation.