JSON API Grafana Datasource

The JSON Datasource executes requests against arbitrary backends and parses JSON response into Grafana dataframes.
JSON Datasource is built on top of the Simple JSON Datasource. It has refactored code, additional features and active development.

Contents

• Installation
• Setup
• API
  • /search
  • /query
  • /annotations
  • /tag-keys
  • /tag-values
• Development Setup

Installation

To install this plugin using the

grafana-cli

 grafana-cli plugins install simpod-json-datasource

See here for more information.

Setup

When adding datasource add your API endpoint to the

URL

API

An OpenAPI definition is defined at openapi.yaml.

To work with this datasource the backend needs to implement 4 endpoints:

• GET /

  with 200 status code response. Used for "Test connection" on the datasource config page.

• POST /search

  returning available metrics when invoked.

• POST /query

  returning metrics based on input.

• POST /annotations

  returning annotations.

Those two urls are optional:

• POST /tag-keys

  returning tag keys for ad hoc filters.

• POST /tag-values

  returning tag values for ad hoc filters.

/search

POST /search

Grafana issues this request on

1. Variables > New/Edit page.

   Query

   field value is passed in a body as

{ "target": "query field value" }

1. Panel > Queries

   page.

   Format As

   and

   Metric

   values are passed in a body as

{ "type": "timeseries", "target": "upper_50" }

The way you handle those values is up to you.

The response body can either contain an array or a map.

Example array response:

["upper_25","upper_50","upper_75","upper_90","upper_95"]

Example map response:

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

/query

POST /query

Example

timeseries

{
  "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,
  "maxDataPoints": 550,
  "targets": [
     { "target": "Packets", "refId": "A", "type": "timeseries", "data": { "additional": "optional json" } },
     { "target": "Errors", "refId": "B", "type": "timeseries" }
  ],
  "adhocFilters": [{
    "key": "City",
    "operator": "=",
    "value": "Berlin"
  }]
}

Example

timeseries

[
  {
    "target":"pps in",
    "datapoints":[
      [622,1450754160000],
      [365,1450754220000]
    ]
  },
  {
    "target":"pps out",
    "datapoints":[
      [861,1450754160000],
      [767,1450754220000]
    ]
  },
  {
    "target":"errors out",
    "datapoints":[
      [861,1450754160000],
      [767,1450754220000]
    ]
  },
  {
    "target":"errors in",
    "datapoints":[
      [861,1450754160000],
      [767,1450754220000]
    ]
  }
]

The relation between

target

target

Example

table

"type": "table"

[
  {
    "columns":[
      {"text":"Time","type":"time"},
      {"text":"Country","type":"string"},
      {"text":"Number","type":"number"}
    ],
    "rows":[
      [1234567,"SE",123],
      [1234567,"DE",231],
      [1234567,"US",321]
    ],
    "type":"table"
  }
]

Additional data

Sending additional data for each metric is supported via the Additional JSON Data input field that allows you to enter JSON.

For example when

{ "additional": "optional json" }

"data"

{ "target": "upper_50", "refId": "A", "type": "timeseries", "data": { "additional": "optional json" } }

You can also enter variables:

/annotations

POST /annotations

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": "JSON Datasource",
    "iconColor": "rgba(255, 96, 96, 1)",
    "enable": true,
    "query": "#deploy"
  },
   "variables": []
}

Grafana expects a response containing an array of annotation objects.

Field explanation: *

text

title

isRegion

time

timeEnd

isRegion

tags

[
  {
    "text": "text shown in body",
    "title": "Annotation Title",
    "isRegion": true,
    "time": "timestamp",
    "timeEnd": "timestamp",
    "tags": ["tag1"]
  }
]

Note: If the datasource is configured to connect directly to the backend, you also need to implement

OPTIONS /annotations

Access-Control-Allow-Headers:accept, content-type
Access-Control-Allow-Methods:POST
Access-Control-Allow-Origin:*

/tag-keys

POST /tag-keys

Example request body

{ }

The tag keys api returns:

[
    {"type":"string","text":"City"},
    {"type":"string","text":"Country"}
]

/tag-values

POST /tag-values

Example request body

{"key": "City"}

The tag values api returns:

[
    {"text": "Eins!"},
    {"text": "Zwei"},
    {"text": "Drei!"}
]

Development Setup

This plugin requires node 6.10.0. Use of Yarn is encouraged to build.

yarn install
yarn run build