JSON

Note

In workspaces that support version 9 or newer, this data source might require you to install the appropriate plugin. For more information, see Grafana plugins.

The JSON data source executes requests against arbitrary backends and parses JSON response into Grafana dataframes.

Adding the data source

1. Open the Grafana console in the Amazon Managed Grafana workspace and make sure you are logged in.

2. In the side menu under Configuration (the gear icon), choose Data Sources.

3. Choose Add data source.

   Note

   If you don't see the Data Sources link in your side menu, it means that your current user does not have the Admin role.

4. Select JSON from the list of data sources.

5. In the URL field, enter your API endpoint. That's where the data source will make requests to.

JSON API

There is an OpenAPI definition for this data source. For more information, see simPod / GrafanaJsonDatasource /

To work with this data source, the backend must implement four endpoints:

• GET / with 200 status code response. Used for "Test connection" on the data source configuration page.

• POST /search returning available metrics when invoked.

• POST /query returning metrics based on input.

• POST /annotations returning annotations.

The following 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

Amazon Managed Grafana issues this request on:

• Variables, New/edit page. The Query field is passed in a body as the following:

  { "target": "query field value" }

• Panel, Queries page. Format As and Metric values are passed in a body as the following:

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

Example timeseries response (metric value as a float, unixtimestamp 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]
    ]
  }
]

The relation between target in request and response is 1:n. You can return multiple targets in response for one requested target.

Example table response to be returned if the metric selected is "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" } is entered into Additional JSON Data , it is attached to the target data under the "data" key:

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

You can also enter variables:

{"key": $variableValue}

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

Amazon Managed Grafana expects a response containing an array of annotation objects.

Field explanation:

• text— (Required) Text for the annotation.

• title— (Optional) The title for the annotation tooltip.

• isRegion— (Optional) Whether this is a region.

• time— (Required) Time since UNIX epoch in milliseconds.

• timeEnd— (Required if isRegion is true) Time since UNIX epoch in milliseconds.

• tags— (Optional) Tags for the annotation.

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

Note

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

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

• Access-Control-Allow-Methods:POST

• Access-Control-Allow-Origin:*

/tag-keys

POST /tag-keys

The JSON request body looks like this:

{ }

The tag keys API returns the following:

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

/tag-values

POST /tag-values

The JSON request body looks like this:

{"key": "City"}

The tag keys API returns the following:

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