Plugins 〉Amazon Redshift

Data Source

grafana

Amazon Redshift

Overview
Installation
Change log
Related content

Grafana 10 breaking change: update Redshift datasource plugin to >=1.8.3

Grafana 10.0.0 was shipped with the new React 18 upgrade. Changes in batching of state updates in React 18 cause a bug in the query editor in Redshift versions <=1.8.2 If you’re using Grafana@>=10.0.0, please update your plugin to version 1.8.3 or higher in your Grafana instance management console.

Redshift data source for Grafana

The Redshift data source plugin allows you to query and visualize Redshift data metrics from within Grafana.

This topic explains options, variables, querying, and other options specific to this data source. Refer to Add a data source for instructions on how to add a data source to Grafana.

Configure the data source in Grafana

To access data source settings, hover your mouse over the Configuration (gear) icon, then click Data Sources, and then click the Amazon Redshift data source.

Name	Description
`Name`	The data source name. This is how you refer to the data source in panels and queries.
`Default`	Default data source means that it will be pre-selected for new panels.
`Authentication Provider`	Specify the provider to get credentials.
`Access Key ID`	If `Access & secret key` is selected, specify the Access Key of the security credentials to use.
`Secret Access Key`	If `Access & secret key` is selected, specify the Secret Key of the security credentials to use.
`Credentials Profile Name`	Specify the name of the profile to use (if you use `~/.aws/credentials` file), leave blank for default.
`Assume Role Arn` (optional)	Specify the ARN of the role to assume.
`External ID` (optional)	If you are assuming a role in another account, that has been created with an external ID, specify the external ID here.
`Endpoint` (optional)	Optionally, specify a custom endpoint for the service.
`Default Region`	Region in which the cluster is deployed.
`AWS Secrets Manager`	To authenticate with Amazon Redshift using AWS Secrets Manager.
`Temporary credentials`	To authenticate with Amazon Redshift using temporary database credentials.
`Serverless`	To use a Redshift Serverless workgroup.
`Cluster Identifier`	Redshift Provisioned Cluster to use (automatically set if using AWS Secrets Manager).
`Workgroup`	Redshift Serverless Workgroup to use.
`Managed Secret`	When using AWS Secrets Manager, select the secret containing the credentials to access the database. Note that Provisioned and Serverless stores credentials in a different format. Refer to Storing database credentials in AWS Secrets Manager for instructions.
`Database User`	User of the database. Automatically set if using AWS Secrets Manager.
`Database`	Name of the database within the cluster or workgroup.
`Send events to Amazon EventBridge`	To send Data API events to Amazon EventBridge for monitoring purpose.

Authentication

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

IAM policies

Grafana needs permissions granted via IAM to be able to read Redshift metrics. You can attach these permissions to IAM roles and utilize Grafana's built-in support for assuming roles. Note that you will need to configure the required policy before adding the data source to Grafana. You can check some predefined policies by AWS here.

Here is a minimal policy example:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowReadingMetricsFromRedshift",
      "Effect": "Allow",
      "Action": [
        "redshift-data:ListTables",
        "redshift-data:DescribeTable",
        "redshift-data:GetStatementResult",
        "redshift-data:DescribeStatement",
        "redshift-data:ListStatements",
        "redshift-data:ListSchemas",
        "redshift-data:ExecuteStatement",
        "redshift-data:CancelStatement",
        "redshift:GetClusterCredentials",
        "redshift:DescribeClusters",
        "redshift-serverless:ListWorkgroups",
        "redshift-serverless:GetCredentials",
        "secretsmanager:ListSecrets"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowReadingRedshiftQuerySecrets",
      "Effect": "Allow",
      "Action": ["secretsmanager:GetSecretValue"],
      "Resource": "*",
      "Condition": {
        "Null": {
          "secretsmanager:ResourceTag/RedshiftQueryOwner": "false"
        }
      }
    }
  ]
}

Query Redshift data

The provided query editor is a standard SQL query editor. Grafana includes some macros to help with writing more complex timeseries queries.

Macros

Macro	Description	Output example
`$__timeEpoch(column)`	`$__timeEpoch` will be replaced by an expression to convert to a UNIX timestamp and rename the column to time	`UNIX_TIMESTAMP(dateColumn) as "time"`
`$__timeFilter(column)`	`$__timeFilter` creates a conditional that filters the data (using `column`) based on the time range of the panel	`time BETWEEN '2017-07-18T11:15:52Z' AND '2017-07-18T11:15:52Z'`
`$__timeFrom()`	`$__timeFrom` outputs the current starting time of the range of the panel with quotes	`'2017-07-18T11:15:52Z'`
`$__timeTo()`	`$__timeTo` outputs the current ending time of the range of the panel with quotes	`'2017-07-18T11:15:52Z'`
`$__timeGroup(column, '1m')`	`$__timeGroup` groups timestamps so that there is only 1 point for every period on the graph	`floor(extract(epoch from time)/60)*60 AS "time"`
`$__schema`	`$__schema` uses the selected schema	`public`
`$__table`	`$__table` outputs a table from the given `$__schema` (it uses the `public` schema by default)	`sales`
`$__column`	`$__column` outputs a column from the current `$__table`	`date`
`$__unixEpochFilter(column)`	`$__unixEpochFilter` be replaced by a time range filter using the specified column name with times represented as Unix timestamp	`column >= 1624406400 AND column <= 1624410000`
`$__unixEpochGroup(column)`	`$__unixEpochGroup` is the same as $__timeGroup but for times stored as Unix timestamp	`floor(time/60)*60 AS "time"`

Table Visualization

Most queries in Redshift will be best represented by a table visualization. Any query will display data in a table. If it can be queried, then it can be put in a table.

This example returns results for a table visualization:

SELECT {column_1}, {column_2} FROM {table};

Timeseries / Graph visualizations

For timeseries / graph visualizations, there are a few requirements:

A column with a date or datetime type must be selected
The date column must be in ascending order (using ORDER BY column ASC)
A numeric column must also be selected

To make a more reasonable graph, be sure to use the $__timeFilter and $__timeGroup macros.

Example timeseries query:

SELECT
  avg(execution_time) AS average_execution_time,
  $__timeGroup(start_time, 'hour'),
  query_type
FROM
  account_usage.query_history
WHERE
  $__timeFilter(start_time)
group by
  query_type,start_time
order by
  start_time,query_type ASC;

Fill value

When data frames are formatted as time series, you can choose how missing values should be filled. This in turn affects how they are rendered: with connected or disconnected values. To configure this value, change the "Fill Value" in the query editor.

Inspecting the query

Because Grafana supports macros that Redshift does not, the fully rendered query, which can be copy/pasted directly into Redshift, is visible in the Query Inspector. To view the full interpolated query, click the Query Inspector button, and the full query will be visible under the "Query" tab.

Templates and variables

To add a new Redshift query variable, refer to Add a query variable. Use your Redshift data source as your data source for the following available queries:

Any value queried from a Redshift table can be used as a variable. Be sure to avoid selecting too many values, as this can cause performance issues.

To display a custom display name for a variable, you can use a query such as SELECT hostname AS text, id AS value FROM MyTable. In this case the variable value field must be a string type or cast to a string type.

After creating a variable, you can use it in your Redshift queries by using Variable syntax. For more information about variables, refer to Templates and variables.

Annotations

Annotations allow you to overlay rich event information on top of graphs. You can add annotations by clicking on panels or by adding annotation queries via the Dashboard menu / Annotations view.

Example query to automatically add annotations:

SELECT
  time as time,
  environment as tags,
  humidity as text
FROM
  $__table
WHERE
  $__timeFilter(time) and humidity > 95

The following table represents the values of the columns taken into account to render annotations:

Name	Description
`time`	The name of the date/time field. Could be a column with a native SQL date/time data type or epoch value.
`timeend`	Optional name of the end date/time field. Could be a column with a native SQL date/time data type or epoch value. (Grafana v6.6+)
`text`	Event description field.
`tags`	Optional field name to use for event tags as a comma separated string.

Provision Redshift data source

You can configure the Redshift data source using configuration files with Grafana's provisioning system. For more information, refer to the provisioning docs page.

Here are some provisioning examples.

Using AWS SDK (default)

apiVersion: 1
datasources:
  - name: Redshift
    type: redshift
    jsonData:
      authType: default
      defaultRegion: eu-west-2

Using credentials' profile name (non-default)

apiVersion: 1
datasources:

name: Redshift
type: redshift
jsonData:
authType: credentials
defaultRegion: eu-west-2
profile: secondary

Using `accessKey` and `secretKey`

apiVersion: 1
datasources:

name: Redshift
type: grafana-redshift-datasource
jsonData:
authType: keys
defaultRegion: eu-west-2
secureJsonData:
accessKey: ‘<your access key>’
secretKey: ‘<your secret key>’

Using AWS SDK Default and ARN of IAM Role to Assume

apiVersion: 1
datasources:
  - name: Redshift
    type: grafana-redshift-datasource
    jsonData:
      authType: default
      assumeRoleArn: arn:aws:iam::123456789012:root
      defaultRegion: eu-west-2

Pre-configured Redshift dashboards

Redshift data source ships with a pre-configured dashboard for some advanced monitoring parameters. This curated dashboard is based on similar dashboards in the AWS Labs repository for Redshift. Check it out for more details.

Follow these instructions for importing a dashboard in Grafana.

Imported dashboards can be found in Configuration > Data Sources > select your Redshift data source > select the Dashboards tab to see available pre-made dashboards.

Get the most out of the plugin

Add Annotations.
Configure and use Templates and variables.
Add Transformations.
Set up alerting; refer to Alerts overview.

Async Query Data Support

Async Query Data support enables an asynchronous query handling flow. With Async Query Data support enabled, queries will be handled over multiple requests (starting, checking its status, and fetching the results) instead of having a query be started and resolved over a single request. This is useful for queries that can potentially run for a long time and timeout. You'll need to ensure the IAM policy used by Grafana allows the following actions redshift-data:ListStatements and redshift-data:CancelStatement.

Async query data support is enabled by default in all Redshift datasources.

Async Query Caching

To enable query caching for async queries, you need to be on Grafana version 10.1 or above, and to set the feature toggles useCachingService and awsAsyncQueryCaching to true. You'll also need to configure query caching for the specific Redshift datasource.

Installing Amazon Redshift on Grafana Cloud:

For more information, visit the docs on plugin installation.

Changelog

1.19.1

Dependabot: Update dependencies in #302, #303, #313, #308, #323, #322:
- path-to-regexp from 1.8.0 to 1.9.0 in the npm_and_yarn group
- micromatch from 4.0.5 to 4.0.8 in the npm_and_yarn group
- actions/checkout from 2 to 4
- actions/setup-node from 3 to 4
- tibdex/github-app-token from 1.8.0 to 2.1.0
- github.com/aws/aws-sdk-go from 1.51.31 to 1.55.5
- github.com/grafana/grafana-plugin-sdk-go from 0.254.0 to 0.259.4
- github.com/grafana/grafana-aws-sdk from 0.31.3 to 0.31.4
- github.com/grafana/sqlds/v4 from 4.1.2 to 4.1.4
- braces from 3.0.2 to 3.0.3 in the npm_and_yarn group
- github.com/stretchr/testify from 1.9.0 to 1.10.0(#321)
- @emotion/css 11.13.4 11.13.5
- @grafana/async-query-data from 0.2.0 to 0.3.0
- @grafana/data from 11.2.2 to 11.3.1
- @grafana/experimental from 2.1.2 to 2.1.4
- @grafana/runtime from 11.2.2 to 11.3.1
- tslib from 2.8.0 to 2.8.1
- @babel/core from 7.25.8 to 7.26.0
- @grafana/eslint-config from 7.0.0 to 8.0.0
- @swc/core from 1.7.36 to 1.9.3
- @swc/helpers from 0.5.13 to 0.5.15
- @swc/jest from 0.2.36 to 0.2.37
- @testing-library/jest-dom from 6.6.0 to 6.6.3
- @types/jest from 29.5.13 to 29.5.14
- @types/lodash from 4.17.10 to 4.17.13
- @types/node from 22.7.5 to 22.10.1
- cspell from 8.15.2 to 8.16.1
- cypress from 7.7.0 to 13.16.0
- prettier from 3.3.3 to 3.4.1
- sass from 1.79.5 to 1.81.0
- sass-loader from 16.0.2 to 16.0.3
- typescript from 5.6.3 to 5.7.2
- webpack from 5.95.0 to 5.96.1
- cross-spawn from 7.0.3 to 7.0.6 in the npm_and_yarn group

1.19.0

Chore: update dependencies #300
Chore: bump dependencies #299
Chore: Update plugin.json keywords #298
Add dependabot for grafana/plugin-sdk-go #296
Fix: don't check slice nilness before checking length #294

1.18.0

Add errorsource in #292

1.17.0

Update grafana/aws-sdk to get new regions

1.16.0

Migrate to new form styling in config and query editors in #287

1.15.2

Fix: use ReadAuthSettings to get authSettings in #288

1.15.1

Upgrade grafana-aws-sdk to replace GetSession usages with GetSessionWithAuthSettings #284

1.15.0

Add keywords by @kevinwcyu in https://github.com/grafana/redshift-datasource/pull/273
Add missing regions and use the region resource handler in the frontend by @iwysiu in https://github.com/grafana/redshift-datasource/pull/276
Plugin.json: update schema reference URL by @leventebalogh in https://github.com/grafana/redshift-datasource/pull/277
Fix E2E: Update region before sending the /secrets resource request by @idastambuk in https://github.com/grafana/redshift-datasource/pull/280
Update for added context in grafana-aws-sdk by @njvrzm in https://github.com/grafana/redshift-datasource/pull/279

New Contributors

@leventebalogh made their first contribution in https://github.com/grafana/redshift-datasource/pull/277
@njvrzm made their first contribution in https://github.com/grafana/redshift-datasource/pull/279

1.14.0

Remove the redshiftAsyncQuerySupport feature toggle + styling improvements in https://github.com/grafana/redshift-datasource/pull/272

1.13.3

Upgrade @grafana/async-query-data from 0.1.10 to 0.1.11 https://github.com/grafana/redshift-datasource/pull/269

1.13.2

Update grafana/aws-sdk-go to 0.20.0 https://github.com/grafana/redshift-datasource/pull/268

1.13.1

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/redshift-datasource/pull/257
Upgrade grafana-plugin-sdk-go; add underscore, debug to package resolutions by @fridgepoet in https://github.com/grafana/redshift-datasource/pull/265

Full Changelog: https://github.com/grafana/redshift-datasource/compare/v1.13.0...v1.13.1

1.13.0

Migrate Query and config editors to new form styling under feature toggle #255
Support Node 18 #249
Fix datasource type in provisioning docs in #246

1.12.2

Fix async queries by not calling ListStatements in GetQueryID #252

1.12.1

upgrade @grafana/aws-sdk to fix a bug in temporary credentials

1.12.0

Update grafana-aws-sdk to v0.19.1 to add il-central-1 to opt-in region list

1.11.1

Upgrade @grafana/async-query-data to reduce minimum query time https://github.com/grafana/redshift-datasource/pull/237

1.11.0

Upgrade grafana/aws-sdk-react dependency #239
Fix connection error when changing access and secret key #235
Support async query caching #233

1.10.0

Add support for Redshift Serverless https://github.com/grafana/redshift-datasource/pull/228 by @yota-p

1.9.0

Upgrade @grafana/aws-sdk to v0.0.47 to support numeric values when applying template variables to SQL queries
Fix async queries and expressions https://github.com/grafana/redshift-datasource/pull/225

1.8.4

Upgrade Readme.md re: Grafana 10 https://github.com/grafana/redshift-datasource/pull/224

1.8.3

Upgrade grafana/aws-sdk-react to 0.0.46 https://github.com/grafana/redshift-datasource/pull/223

1.8.2

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

1.8.1

Update async-query-data with a fix for errors in #220

1.8.0

Update backend dependencies

1.7.0

Fix converting rows with FLOAT, FLOAT4, and BOOLEAN by @iwysiu in #213
Add header component to Query Editor by @idastambuk in #214
Use organization ISSUE_COMMANDS_TOKEN with reduced scope by @iwysiu in #210

1.6.0

Remove run and cancel buttons in annotations editor in https://github.com/grafana/redshift-datasource/pull/206

1.5.0

Migrate to create-plugin by @iwysiu in https://github.com/grafana/redshift-datasource/pull/195
Update code coverage in workflow to latest by @idastambuk in https://github.com/grafana/redshift-datasource/pull/198
Update @grafana/aws-sdk by @kevinwcyu in https://github.com/grafana/redshift-datasource/pull/199
Update @grafana/ packages by @idastambuk in https://github.com/grafana/redshift-datasource/pull/201
Upgrade grafana-aws-sdk to v0.12.0 by @fridgepoet in https://github.com/grafana/redshift-datasource/pull/202

1.4.1

Hide the stop button when async query data support is not enabled https://github.com/grafana/redshift-datasource/pull/196

1.4.0

Add Async Query Data Support https://github.com/grafana/redshift-datasource/pull/177

1.3.3

Update @grafana dependencies to v8.5.10 https://github.com/grafana/redshift-datasource/pull/194

1.3.2

Security: Upgrade Go in build process to 1.19.3

1.3.1

Security: Upgrade Go in build process to 1.19.2

1.3.0

Upgrade to grafana-aws-sdk v0.11.0 by @fridgepoet in https://github.com/grafana/redshift-datasource/pull/183

1.2.0

Add database security monitoring dashboards by @yota-p in https://github.com/grafana/redshift-datasource/pull/175

1.1.0

Add support for context aware autocompletion by @sunker in https://github.com/grafana/redshift-datasource/pull/174

1.0.7

Bug fix for auth issues with when using keys and dependency upgrades (https://github.com/grafana/redshift-datasource/pull/165)
Updates to code coverage

1.0.6

What's Changed

Update grafana-aws-sdk by @andresmgot in https://github.com/grafana/redshift-datasource/pull/146
Autocomplete: Render SQL editor in case feature toggle is enabled by @sunker in https://github.com/grafana/redshift-datasource/pull/151
fix: WLM panels query fix by @vgkowski in https://github.com/grafana/redshift-datasource/pull/152
Custom redshift language by @sunker in https://github.com/grafana/redshift-datasource/pull/154
Align Monaco language with official language ref by @sunker in https://github.com/grafana/redshift-datasource/pull/156

Full Changelog: https://github.com/grafana/redshift-datasource/compare/v1.0.5...v1.0.6