Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Beginner Guides

Data Sources

AWS CloudWatch

Enterprise Open source

Using AWS CloudWatch in Grafana

Grafana ships with built in support for CloudWatch. You just have to add it as a data source and you will be ready to build dashboards for your CloudWatch metrics.

Adding the data source to Grafana

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Dashboards link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select Cloudwatch from the Type dropdown.

NOTE: If at any moment you have issues with getting this datasource to work and Grafana is giving you undescriptive errors then don’t forget to check your log file (try looking in /var/log/grafana/grafana.log).

Name	Description
Name	The data source name. This is how you refer to the data source in panels & queries.
Default	Default data source means that it will be pre-selected for new panels.
Default Region	Used in query editor to set region (can be changed on per query basis)
Custom Metrics namespace	Specify the CloudWatch namespace of Custom metrics
Auth Provider	Specify the provider to get credentials.
Credentials profile name	Specify the name of the profile to use (if you use `~/.aws/credentials` file), leave blank for default.
Assume Role Arn	Specify the ARN of the role to assume

Authentication

IAM Roles

Currently all access to CloudWatch is done server side by the Grafana backend using the official AWS SDK. If your Grafana server is running on AWS you can use IAM Roles and authentication will be handled automatically.

Checkout AWS docs on IAM Roles

IAM Policies

Grafana needs permissions granted via IAM to be able to read CloudWatch metrics and EC2 tags/instances/regions. You can attach these permissions to IAM roles and utilize Grafana’s built-in support for assuming roles.

Here is a minimal policy example:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowReadingMetricsFromCloudWatch",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:GetMetricData"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowReadingTagsInstancesRegionsFromEC2",
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeTags",
                "ec2:DescribeInstances",
                "ec2:DescribeRegions"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowReadingResourcesForTags",
            "Effect" : "Allow",
            "Action" : "tag:GetResources",
            "Resource" : "*"
        }
    ]
}

AWS credentials

If Auth Provider is Credentials file, Grafana try to get credentials by following order.

Environment variables. (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)
Hard-code credentials.
Shared credentials file.
IAM role for Amazon EC2.

Checkout AWS docs on Configuring the AWS SDK for Go

AWS credentials file

Create a file at ~/.aws/credentials. That is the HOME path for user running grafana-server. > NOTE: If you think you have the credentials file in the right place but it is still not working then you might try moving your .aws file to ‘/usr/share/grafana/’ and make sure your credentials file has at most 0644 permissions.

Example content:

[default]
aws_access_key_id = asdsadasdasdasd
aws_secret_access_key = dasdasdsadasdasdasdsa
region = us-west-2

Metric Query Editor

You need to specify a namespace, metric, at least one stat, and at least one dimension.

Metric Math

You can now create new time series metrics by operating on top of Cloudwatch metrics using mathematical functions. Arithmetic operators, unary subtraction and other functions are supported to be applied on cloudwatch metrics. More details on the available functions can be found on AWS Metric Math

As an example, if you want to apply arithmetic operator on a metric, you can do it by giving an alias(a unique string) to the raw metric as shown below. Then you can use this alias and apply arithmetic operator to it in the Expression field of created metric.

Templated queries

Instead of hard-coding things like server, application and sensor name in you metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns makes it easy to change the data being displayed in your dashboard.

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query variable

CloudWatch Datasource Plugin provides the following queries you can specify in the Query field in the Variable edit view. They allow you to fill a variable’s options list with things like region, namespaces, metric names and dimension keys/values.

In place of region you can specify default to use the default region configured in the datasource for the query, e.g. metrics(AWS/DynamoDB, default) or dimension_values(default, ..., ..., ...).

Read more about the available dimensions in the CloudWatch Metrics and Dimensions Reference.

Name	Description
regions()	Returns a list of regions AWS provides their service.
namespaces()	Returns a list of namespaces CloudWatch support.
metrics(namespace, [region])	Returns a list of metrics in the namespace. (specify region or use “default” for custom metrics)
dimension_keys(namespace)	Returns a list of dimension keys in the namespace.
dimension_values(region, namespace, metric, dimension_key, [filters])	Returns a list of dimension values matching the specified `region`, `namespace`, `metric`, `dimension_key` or you can use dimension `filters` to get more specific result as well.
ebs_volume_ids(region, instance_id)	Returns a list of volume ids matching the specified `region`, `instance_id`.
ec2_instance_attribute(region, attribute_name, filters)	Returns a list of attributes matching the specified `region`, `attribute_name`, `filters`.
resource_arns(region, resource_type, tags)	Returns a list of ARNs matching the specified `region`, `resource_type` and `tags`.

For details about the metrics CloudWatch provides, please refer to the CloudWatch documentation.

Examples templated Queries

Example dimension queries which will return list of resources for individual AWS Services:

Query	Service
dimension_values(us-east-1,AWS/ELB,RequestCount,LoadBalancerName)	ELB
dimension_values(us-east-1,AWS/ElastiCache,CPUUtilization,CacheClusterId)	ElastiCache
dimension_values(us-east-1,AWS/Redshift,CPUUtilization,ClusterIdentifier)	RedShift
dimension_values(us-east-1,AWS/RDS,CPUUtilization,DBInstanceIdentifier)	RDS
dimension_values(us-east-1,AWS/S3,BucketSizeBytes,BucketName)	S3
dimension_values(us-east-1,CWAgent,disk_used_percent,device,{“InstanceId”:"$instance_id"})	CloudWatch Agent
resource_arns(eu-west-1,elasticloadbalancing:loadbalancer,{“elasticbeanstalk:environment-name”:[“myApp-dev”,“myApp-prod”]})	ELB
resource_arns(eu-west-1,ec2:instance,{“elasticbeanstalk:environment-name”:[“myApp-dev”,“myApp-prod”]})	EC2

ec2_instance_attribute examples

JSON filters

The ec2_instance_attribute query takes filters in JSON format. You can specify pre-defined filters of ec2:DescribeInstances. Note that the actual filtering takes place on Amazon’s servers, not in Grafana.

Filters syntax:

{ filter_name1: [ filter_value1 ], filter_name2: [ filter_value2 ] }

Example ec2_instance_attribute() query

ec2_instance_attribute(us-east-1, InstanceId, { "tag:Environment": [ "production" ] })

Selecting Attributes

Only 1 attribute per instance can be returned. Any flat attribute can be selected (i.e. if the attribute has a single value and isn’t an object or array). Below is a list of available flat attributes:

AmiLaunchIndex
Architecture
ClientToken
EbsOptimized
EnaSupport
Hypervisor
IamInstanceProfile
ImageId
InstanceId
InstanceLifecycle
InstanceType
KernelId
KeyName
LaunchTime
Platform
PrivateDnsName
PrivateIpAddress
PublicDnsName
PublicIpAddress
RamdiskId
RootDeviceName
RootDeviceType
SourceDestCheck
SpotInstanceRequestId
SriovNetSupport
SubnetId
VirtualizationType
VpcId

Tags can be selected by prepending the tag name with Tags.

Example ec2_instance_attribute() query

ec2_instance_attribute(us-east-1, Tags.Name, { "tag:Team": [ "sysops" ] })

Using json format template variables

Some of query takes JSON format filter. Grafana support to interpolate template variable to JSON format string, it can use as filter string.

If env = 'production', 'staging', following query will return ARNs of EC2 instances which Environment tag is production or staging.

resource_arns(us-east-1, ec2:instance, {"Environment":${env:json}})

Cost

Amazon provides 1 million CloudWatch API requests each month at no additional charge. Past this, it costs $0.01 per 1,000 GetMetricStatistics or ListMetrics requests. For each query Grafana will issue a GetMetricStatistics request and every time you pick a dimension in the query editor Grafana will issue a ListMetrics request.

Configure the Datasource with Provisioning

It’s now possible to configure datasources using config files with Grafana’s provisioning system. You can read more about how it works and all the settings you can set for datasources on the provisioning docs page

Here are some provisioning examples for this datasource.

Using a credentials file

apiVersion: 1

datasources:
  - name: Cloudwatch
    type: cloudwatch
    jsonData:
      authType: credentials
      defaultRegion: eu-west-2

Using accessKey and secretKey

apiVersion: 1

datasources:
  - name: Cloudwatch
    type: cloudwatch
    jsonData:
      authType: keys
      defaultRegion: eu-west-2
    secureJsonData:
      accessKey: "<your access key>"
      secretKey: "<your secret key>"