Plugins 〉Amazon Timestream
Amazon Timestream
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
- In the side menu under the Configuration link, click on Data Sources.
- Click the Add data source button.
- 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.
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 example | Description |
---|---|
$__database | Will specify the selected database. This may use the default from the datasource config, or the explicit value from the query editor. |
$__table | Will specify the selected database. This may use the default from the datasource config, or the explicit value from the query editor. |
$__measure | Will specify the selected measure. This may use the default from the datasource config, or the explicit value from the query editor. |
$__timeFilter | Will be replaced by an expression that limits the time to the dashboard range. |
$__timeFrom | Will be replaced by the number in milliseconds at the start of the dashboard range. |
$__timeTo | Will be replaced by the number in milliseconds at the end of the dashboard range. |
$__interval_ms | Will be replaced by a number in time format that represents the amount of time a single pixel in the graph should cover. |
$__interval_raw_ms | Will 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
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 "Wait for all queries" checkbox underneath the "Render" query editor section for 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 AWS SDK (default)
apiVersion: 1
datasources:
- name: Timestream
type: grafana-timestream-datasource
jsonData:
authType: default
defaultRegion: eu-west-2
Using credentials' profile name (non-default)
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>’
Using AWS SDK Default and ARN of IAM Role to Assume
apiVersion: 1
datasources:
- name: Timestream
type: grafana-timestream-datasource
jsonData:
authType: default
assumeRoleArn: arn:aws:iam::123456789012:root
defaultRegion: eu-west-2
Sample Dashboard
This plugin contains one sample dashboard. Please consult the Sample Application section in the official Timestream doc to set it up.
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
.h4 . .mb-0 }
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Grafana Cloud Free
- Free tier: Limited to 3 users
- Paid plans: $55 / user / month above included usage
- Access to all Enterprise Plugins
- Fully managed service (not available to self-manage)
Self-hosted Grafana Enterprise
- Access to all Enterprise plugins
- All Grafana Enterprise features
- Self-manage on your own infrastructure
Installing Amazon Timestream 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.
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 Amazon Timestream 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.
Change Log
All notable changes to this project will be documented in this file.
2.9.9
- Fix "Wait for All Queries" toggle in #313
- Fix errors in LongToWide transformation in #311
- Chore: Update plugin.json keywords in #310
- Update grafana-plugin-sdk-go and grafana-aws-sdk in #309
- fix: linter complaints in #308
- Bump path-to-regexp from 1.8.0 to 1.9.0 in #303
- Docs: Updates and improvements in #302
- Add dependabot for grafana/plugin-sdk-go in #307
2.9.8
- Bump webpack from 5.92.1 to 5.94.0 in #301
- Bump micromatch from 4.0.7 to 4.0.8 in #299
- Bump fast-loops from 1.1.3 to 1.1.4 in #298
2.9.7
2.9.6
- Bugfix: Fix $interval variable interpolation in #291
2.9.5
- Chore: update dependencies in #290
2.9.4
- Fix: use ReadAuthSettings to get authSettings in #289
2.9.3
- Upgrade grafana-aws-sdk and other packages #285
2.9.2
- Add keywords by @kevinwcyu in https://github.com/grafana/timestream-datasource/pull/278
- Bring in security fixes in go 1.21.8
2.9.1
- Update grafana/aws-sdk to 0.20.0 to add a new supported region in #274
- Query Editor: Fix table and database mapping in #272
2.9.0
- Bump jest-dom in #270
- Query Editor: Stop running query automatically when all macros are selected in #269
- Bump go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc from 0.45.0 to 0.46.0 in #267
2.8.0
- Support Node 18 by @kevinwcyu in https://github.com/grafana/timestream-datasource/pull/245
- Bump word-wrap from 1.2.3 to 1.2.5 by @dependabot in https://github.com/grafana/timestream-datasource/pull/246
- Bump semver from 5.7.1 to 5.7.2 by @dependabot in https://github.com/grafana/timestream-datasource/pull/235
- Bump golang.org/x/net from 0.9.0 to 0.17.0 by @dependabot in https://github.com/grafana/timestream-datasource/pull/250
- Bump postcss from 8.4.18 to 8.4.31 by @dependabot in https://github.com/grafana/timestream-datasource/pull/249
- Bump @babel/traverse from 7.18.13 to 7.23.2 by @dependabot in https://github.com/grafana/timestream-datasource/pull/252
- Bump google.golang.org/grpc from 1.54.0 to 1.56.3 by @dependabot in https://github.com/grafana/timestream-datasource/pull/253
- Bump go.opentelemetry.io/contrib/instrumentation/net/http/httptrace/otelhttptrace from 0.37.0 to 0.44.0 by @dependabot in https://github.com/grafana/timestream-datasource/pull/251
- Bump @babel/traverse from 7.18.13 to 7.23.2 by @dependabot in https://github.com/grafana/timestream-datasource/pull/255
- Bump google.golang.org/grpc from 1.58.2 to 1.58.3 by @dependabot in https://github.com/grafana/timestream-datasource/pull/254
- Upgrade underscore, d3-color, debug, cosmiconfig, yaml dependencies by @fridgepoet in https://github.com/grafana/timestream-datasource/pull/263
- Bump yaml from 2.1.3 to 2.3.4 by @dependabot in https://github.com/grafana/timestream-datasource/pull/264
Full Changelog: https://github.com/grafana/timestream-datasource/compare/v2.7.1...v2.8.0
2.7.1
- Update @grafana/aws-sdk to fix a bug in temporary credentials
2.7.0
- Update grafana-aws-sdk to v0.19.1 to add
il-central-1
to opt-in region list
2.6.2
- Update grafana-aws-sdk-react version to use grafana/runtime instead of grafanaBootData #237
- Remove code coverage workflow #234
2.6.1
- Update grafana-aws-sdk version to include new region in opt-in region list https://github.com/grafana/grafana-aws-sdk/pull/80
- Security: Upgrade Go in build process to 1.20.4
- Update grafana-plugin-sdk-go version to 0.161.0 to avoid a potential http header problem. https://github.com/grafana/athena-datasource/issues/233
2.6.0
- Update backend dependencies
2.5.0
- Update @grafana/aws-sdk by @kevinwcyu in https://github.com/grafana/timestream-datasource/pull/216
- Increase label width to fix overflow. by @chinu-anand in https://github.com/grafana/timestream-datasource/pull/217
- migrate to create-plugin by @iwysiu in https://github.com/grafana/timestream-datasource/pull/199
- Upgrade grafana-aws-sdk by @fridgepoet in https://github.com/grafana/timestream-datasource/pull/223
Full Changelog: https://github.com/grafana/timestream-datasource/compare/v2.4.0...v2.5.0
2.4.0
- Fix: SQLEditor: Use queryRef to call onChange #209
- Chore: Update version of code-coverage #211
- Feature: Timestream is now available in us-gov-west-1 #207
2.3.2
- Security: Upgrade Go in build process to 1.19.3
2.3.1
- Security: Upgrade Go in build process to 1.19.2
v2.3.0
- Change timestamp fieldType to be nullable by @nekketsuuu in https://github.com/grafana/timestream-datasource/pull/184
- Upgrade to grafana-aws-sdk v0.11.0 by @fridgepoet in https://github.com/grafana/timestream-datasource/pull/195
v2.2.0
- Add support for context aware autocompletion by @sunker in https://github.com/grafana/timestream-datasource/pull/188
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 authentication 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