Plugins 〉Amazon Timestream

Data Source
grafana

Amazon Timestream

  • Overview
  • Installation
  • Change log
  • Related content

Timestream Datasource

The Timestream datasource plugin provides a support for Amazon Timestream. Add it as a data source, then you are ready to build dashboards using timestream query results

Add the data source

  1. In the side menu under the Configuration link, click on Data Sources.
  2. Click the Add data source button.
  3. Select Timestream in the Time series databases section.

Authentication

For authentication options and configuration details, see AWS authentication topic.

IAM policies

Grafana needs permissions granted via IAM to be able to read data from the Timestream API. You can attach these permissions to the IAM role or IAM user configured in the previous step.

Here is a policy example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["timestream:*"],
      "Resource": "*"
    }
  ]
}

Query editor

The query editor accepts timestream syntax in addition to the macros listed above and any dashboard template variables.

query-editor

Type ctrl+space to open open the IntelliSense suggestions

Macros

To simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros.

Macro exampleDescription
$__databaseWill specify the selected database. This may use the default from the datasource config, or the explicit value from the query editor.
$__tableWill specify the selected database. This may use the default from the datasource config, or the explicit value from the query editor.
$__measureWill specify the selected measure. This may use the default from the datasource config, or the explicit value from the query editor.
$__timeFilterWill be replaced by an expression that limits the time to the dashboard range.
$__timeFromWill be replaced by the number in milliseconds at the start of the dashboard range.
$__timeToWill be replaced by the number in milliseconds at the end of the dashboard range.
$__interval_msWill be replaced by a number in time format that represents the amount of time a single pixel in the graph should cover.
$__interval_raw_msWill be replaced by the number in milliseconds that represents the amount of time a single pixel in the graph should cover.

Using Variables in Queries

Instead of hard-coding server, application and sensor names in your Timestream queries, you can use variables. The variables are listed as dropdown select boxes at the top of the dashboard. These dropdowns make it easy to change the display of data in your dashboard.

For an introduction to templating and template variables, refer to the Templating documentation.

Disabling quoting for multi-value variables

Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if server01 and server02 are selected then it will be formatted as: 'server01', 'server02'. To disable quoting, use the csv formatting option for variables:

${servers:csv}

Read more about variable formatting options in the Variables documentation.

Alerting

See the Alerting documentation for more on Grafana alerts.

Unified Alerting queries should contain a time series field. Queries without this field will return an error: "input data must be a wide series but got type long". To return time series, you can use the CREATE_TIME_SERIES function. For example:

SELECT
    silo, microservice_name, instance_name,
    CREATE_TIME_SERIES(time, measure_value::double) AS gc_pause
FROM $__database.$__table
WHERE $__timeFilter
    AND measure_name = '$__measure'
    AND region = 'ap-northeast-1'
    AND cell = 'ap-northeast-1-cell-5'
    AND silo = 'ap-northeast-1-cell-5-silo-2'
    AND availability_zone = 'ap-northeast-1-3'
    AND microservice_name = 'zeus'
GROUP BY region,
    cell,
    silo,
    availability_zone,
    microservice_name,
    instance_name,
    process_name,
    jdk_version
ORDER BY AVG(measure_value::double) DESC
LIMIT 3

Note: Results for Timestream queries are returned in different pages (if necessary) by default. To ensure that all pages are processed before evaluating an alert, mark the checkbox "Render after all queries finish" in all alert queries.

Configure the data source with provisioning

You can configure data sources using config files with Grafana's provisioning system. You can read more about how it works and all the settings you can set for data sources on the provisioning docs page.

Here are some provisioning examples for this data source.

Using a credentials file

If you are using Credentials file authentication type, then you should use a credentials file with a config like this.

apiVersion: 1

datasources:

  • name: Timestream type: grafana-timestream-datasource jsonData: authType: credentials defaultRegion: us-east-1

Using accessKey and secretKey

apiVersion: 1

datasources:

  • name: Timestream type: grafana-timestream-datasource jsonData: authType: keys defaultRegion: us-east-1 secureJsonData: accessKey: ‘<your access key>’ secretKey: ‘<your secret key>’

Sample Dashboard

This plugin contains one sample dashboard. Please consult the Sample Application section in the official Timestream doc to set it up.

Installing Amazon Timestream on Grafana Cloud:

For more information, visit the docs on plugin installation.

Change Log

All notable changes to this project will be documented in this file.

v2.1.0

  • Add 'ap-southeast-2' and 'ap-northeast-1' regions #178

v2.0.1

  • Bug fix for issue logging in with incorrect keys: https://github.com/grafana/timestream-datasource/pull/176
  • Code Coverage Check updates

v2.0.0

  • Breaking Change: Timestream data source now requires Grafana 8.0+ to run.
  • Fix: Allow null data points for time series #170

v1.5.2

  • Fix Panic while parsing null timestamps (#165)

v1.5.1

  • Always apply double quotes to database and table name (#155)

v1.5.0

  • Revamp query editor.
  • Add toggle to avoid streaming responses.
  • Add $__interval variable.
  • Modify the User-Agent for requests. Now it will follow this form: "aws-sdk-go/$aws-sdk-version ($go-version; $OS;) Timestream/$timestream-version-$git-hash Grafana/$grafana-version".
  • Fixes bugs for Endpoint and Assume Role settings.

v1.4.0

  • Add macros for raw values of interval, from, to #98
  • Quote and join multiple variables #118
  • Add stats for bytes metered and scanned #110

v1.3.3

  • Support for multiple timeseries columns
  • Improved support for custom endpoint

v1.3.2

  • Adding eu-central-1 region
  • renamed "master" branch to "main"
  • build with Golang 1.6

v1.3.1

  • Execute each query in its own request, this will support multiple queries that require multiple pages to complete
  • Upgrade shared authenticaiton library
  • Bump minimum grafana runtime to 7.5

v1.3.0

  • fix bug with supporting multi-page timeseries results
  • Use a shared authentication library and UI component
  • Bump minimum grafana runtime to 7.4

v1.2.0

  • Support $__timefilter on armhf (#52, @mg-arne)
  • Add $__now_ms macro (#49, @squalou)
  • Fixed region picker default values

v1.1.2

  • Fix template variable queries
  • Only show valid regions

v1.1.1

  • Avoid double escaping
  • support template variables in query

v1.1.0

  • Updated authentication to match builtin cloudwatch authentication
  • Include query status in metadata
  • Examples and query suggestions now quote all names

v1.0.0

  • Initial Release