Plugins 〉JSON
JSON
JSON API Grafana Datasource
The JSON Datasource executes requests against arbitrary backends and parses JSON response into Grafana dataframes.
Contents
Installation
To install this plugin using the grafana-cli
tool:
grafana-cli plugins install simpod-json-datasource
See here for more information.
Setup
When adding datasource add your API endpoint to the URL
field. That's where datasource will make requests to.
If you want to add custom headers, keep Access set to Server
.
API
An OpenAPI definition is defined at openapi.yaml.
To work with this datasource the backend needs to implement 3 endpoints:
GET /
with 200 status code response. Used for "Test connection" on the datasource config page.POST /search
to return available metrics.POST /query
to return panel data or annotations.
Those 3 endpoints are optional:
POST /variable
to return data for Variable of typeQuery
.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
- Variables > New/Edit page.
Query
field value is passed in a body as shown below (template variables are expanded as regex by default)
{ "target": "query field value" }
Alternatively, flick on the "Raw JSON" switch to provide a full valid JSON string in the query field which will be passed in the request body as a native JSON object.
Template variables will be expanded as a JSON array. For example, selecting two items in a multi-field dropdown $myservers
{"selectedservers":$myservers}
will be expanded to
{"selectedservers":["server1","server2"]}
Panel > Queries
page.Format As
andMetric
values are passed in a body as
{ "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 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,
"maxDataPoints": 550,
"targets": [
{ "target": "Packets", "refId": "A", "payload": { "additional": "optional json" } },
{ "target": "Errors", "refId": "B" }
],
"adhocFilters": [{
"key": "City",
"operator": "=",
"value": "Berlin"
}]
}
Response body can contain anything that is or can be converted to a Grafana DataFrame using this function. Returned data will be mapped to a DataFrame through that.
Example response (metric value as a float , unix timestamp in milliseconds):
[
{
"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]
]
}
]
[
{
"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"
}
]
The relation between target
in request and response is 1:n. You can return multiple targets in response for one requested target
.
Payload
Sending additional data for each metric is supported via the Payload
input field that allows you to enter any JSON string.
For example, when { "additional": "optional json" }
is entered into Payload
input, it is attached to the target data under "payload"
key:
{ "target": "upper_50", "refId": "A", "payload": { "additional": "optional json" } }
You can also enter variables:
/variable
POST /variable
Example request body:
{
"payload":{"target":"systems"},
"range":{
"from":"2022-02-14T08:09:32.164Z",
"to":"2022-02-21T08:09:32.164Z",
"raw":{"from":"now-7d","to":"now"}
}
}
"payload"
is value from your input in Variable edit form.
Example response
[
{"__text":"Label 1", "__value":"Value1"},
{"__text":"Label 2", "__value":"Value2"},
{"__text":"Label 3", "__value":"Value3"}
]
/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!"}
]
Grafana Cloud Pro
- $25 / user / month and includes a free trial for new users
- Available with a Grafana Cloud Pro plan
- Access to 1 Enterprise plugin
- Fully managed service (not available to self-manage)
Grafana Cloud Advanced / Grafana Enterprise
- Available with a Grafana Cloud Advanced plan or Grafana Enterprise license
- Access to all Enterprise plugins
- Run fully managed or self-manage on your own infrastructure
Installing JSON on Grafana Cloud:
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
For more information, visit the docs on plugin installation.
Installing on a local Grafana:
For local instances, plugins are installed and updated via a simple CLI command. Plugins are not updated automatically, however you will be notified when updates are available right within your Grafana.
1. Install the Data Source
Use the grafana-cli tool to install JSON from the commandline:
grafana-cli plugins install
The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.
Alternatively, you can manually download the .zip file for your architecture below and unpack it into your grafana plugins directory.
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
2. Configure the Data Source
Accessed from the Grafana main menu, newly installed data sources can be added immediately within the Data Sources section.
Next, click the Add data source button in the upper right. The data source will be available for selection in the Type select box.
To see a list of installed data sources, click the Plugins item in the main menu. Both core data sources and installed data sources will appear.
Changelog
v0.2.4
- Fixed order of processing Additional JSON, so we're first replacing variables and JSON parse after that in #149 (@istvan86-nagy)
v0.2.3
- Upgrade deps to @grafana v7.3
- Require Grafana 7.3