streams-redistimeseries-grafana/grafana-data/plugins/grafana-simple-json-datasource/README.md

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.
• /tag-keys should return tag keys for ad hoc filters.
• /tag-values should return tag values for ad hoc filters.

Installation

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

• https://github.com/bergquist/fake-simple-json-datasource
• https://github.com/smcquay/jsonds
• https://github.com/ContextLogic/eventmaster
• https://gist.github.com/linar-jether/95ff412f9d19fdf5e51293eb0c09b850 (Python/pandas backend)

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
    "datapoints":[
      [622,1450754160000],  // Metric value as a float , unixtimestamp in milliseconds
      [365,1450754220000]
    ]
  },
  {
    "target":"upper_90",
    "datapoints":[
      [861,1450754160000],
      [767,1450754220000]
    ]
  }
]

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

[
  {
    "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"
  }
]

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
Access-Control-Allow-Methods:POST
Access-Control-Allow-Origin:*

Search API

Example request

{ target: 'upper_50' }

The search api can either return an array or 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} ]

Tag Keys API

Example request

{ }

The tag keys api returns:

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

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

Changelog

1.4.0

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

1.3.5

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

1.3.4

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

1.3.3

• Adds support for basic authentication

1.2.4

• Add support returning sets in the search endpoint

1.2.3

• Allow nested templates in find metric query. #23

1.2.2

• 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.