Connect Amazon CloudWatch to Grafana: Setup Guide
Published on · Updated on
Rewrote the setup for managed and self-hosted Grafana with current IAM, query, cross-account, alerting, and cost guidance.
Grafana’s built-in Amazon CloudWatch data source can query CloudWatch metrics and logs for dashboards and alerts. Choose Amazon Managed Grafana if you want AWS to operate the Grafana service, or connect a self-hosted Grafana server using an IAM role or another temporary-credential provider. In both cases, AWS credentials stay on the Grafana server side; browser users do not send AWS keys to CloudWatch.
This guide walks through the identity setup, the CloudWatch data source, one metrics query, one Logs Insights query, and ways to control access and query costs. Grafana includes the CloudWatch data source, so a separate plugin installation is not needed in current Grafana versions. Grafana’s CloudWatch data source documentation describes supported metrics, logs, and alerting features.
Prerequisites
Before connecting, have an AWS account and Region with CloudWatch metrics or log groups, a Grafana workspace or server where you can add a data source, and an AWS identity that can query the features you plan to use. The backend that runs Grafana must reach the CloudWatch APIs for the selected Region and AWS STS if it assumes a role. For self-hosted Grafana, allow the needed outbound HTTPS traffic from the host. For Amazon Managed Grafana, network setup depends on whether you attach the workspace to a VPC.
Choose a Grafana deployment
The metrics and logs workflow is similar across Grafana deployments. Available authentication providers, screen labels, and some settings depend on the Grafana product and version; hosting also determines how Grafana receives AWS credentials and who maintains the service.
| Grafana option | AWS authentication | Use it when |
|---|---|---|
| Amazon Managed Grafana | A workspace IAM role. AWS can create and manage the role and its selected data-source permissions. | You want AWS to operate Grafana and need a managed path to AWS data. |
| Self-hosted Grafana on EC2, ECS, or EKS | Attach an IAM role to the EC2 instance, ECS task, or Kubernetes service account and use the AWS SDK default credential chain. | You need to control the Grafana host, version, network, or plugins. |
| Grafana Cloud | Use Grafana’s Assume Role provider for CloudWatch, with a target AWS role that trusts Grafana’s AWS account and the external ID shown in Grafana. | You want Grafana Labs to operate the Grafana service. |
For self-hosted Grafana outside AWS, configure a credential provider that supplies temporary AWS credentials to the Grafana process. A credentials file or static access key is available in some configurations, but long-lived IAM user keys create storage and rotation work; prefer a workload identity or temporary role credentials where your hosting platform supports them. The available providers depend on the Grafana product and server configuration. See Grafana’s AWS authentication options.
Set up AWS authentication and permissions
Configure the workspace or host role
Amazon Managed Grafana: When creating a workspace, choose service-managed permissions for the current account or, where supported, the organization, then select CloudWatch as an AWS data source. Amazon Managed Grafana creates the workspace roles and policies for the selected sources. You still add the CloudWatch data source inside the Grafana workspace. If you choose customer-managed permissions, provide a workspace IAM role whose trust policy allows the service principal grafana.amazonaws.com, and attach the permissions for the AWS data sources that role must query. AWS describes the modes and generated roles in its Amazon Managed Grafana permissions guide.
Self-hosted Grafana in AWS: Give the runtime an IAM role rather than putting credentials in the data-source form. For EC2, attach the role through an instance profile; for ECS, use a task role; for EKS, use a role associated with the Grafana service account. In the CloudWatch data source, choose AWS SDK Default so Grafana can use the credentials provided to its process. The role’s trust policy must match the AWS service or identity provider for that runtime. The grafana.amazonaws.com principal above is for an Amazon Managed Grafana workspace role; it is not the trust principal for an EC2 instance role.
Separate role trust from permissions
A trust policy answers who may assume a role. A permissions policy answers what that role may do after it is assumed. For a self-hosted cross-account setup, the Grafana host role needs sts:AssumeRole scoped to the target role ARN, and the target role must trust that exact source role. The target role receives the CloudWatch read permissions. Do not put CloudWatch permissions in the trust policy or add iam:PassRole to the Grafana query role; passing a role is an administrative setup action, not a requirement for querying CloudWatch.
For Grafana Cloud’s Grafana Assume Role provider, create the AWS role using the account ID and external ID shown on the CloudWatch data source’s settings page. Keep the sts:ExternalId condition in the trust policy. Grafana documents the account-specific setup in its AWS authentication guide.
Grant only the query permissions you use
Start with the APIs needed by the query types you will use. Add discovery and convenience permissions only when you use the matching Grafana feature. Grafana’s permission reference maps each action to its purpose.
| Grafana feature | Actions | When to grant |
|---|---|---|
| CloudWatch metric queries | cloudwatch:ListMetrics, cloudwatch:GetMetricData | Required to discover metrics and retrieve their data. |
| Logs Insights queries | logs:DescribeLogGroups, logs:StartQuery, logs:StopQuery, logs:GetQueryResults | Required to select log groups and run or retrieve a query. |
| CloudWatch Logs data-source selector | logs:ListAggregateLogGroupSummaries | Optional: only when selecting CloudWatch Logs data sources by producer/type instead of selecting log groups; see the Grafana query editor guide. |
| Log query editor and raw events | logs:GetLogGroupFields, logs:GetLogEvents | Optional: field suggestions and queries that read individual log events. |
| CloudWatch alarm panels or alarm queries | cloudwatch:DescribeAlarms, cloudwatch:DescribeAlarmsForMetric, cloudwatch:DescribeAlarmHistory | Optional: only if Grafana displays alarm details or history. |
| Dynamic Region or resource variables | ec2:DescribeRegions, ec2:DescribeInstances, ec2:DescribeTags, ec2:DescribeVolumes, tag:GetResources | Optional: grant only for the region, EC2, EBS volume, tag, or resource-ARN selectors you use. |
| Specialized CloudWatch queries | cloudwatch:GetInsightRuleReport, pi:GetResourceMetrics | Optional: Contributor Insights or supported Performance Insights metrics. |
If a log group has a data-protection policy, CloudWatch masks matching values in query results. logs:Unmask is granted to the AWS role used by the Grafana data source, so it applies to queries made with that shared identity rather than to an individual Grafana viewer. Grant it only when unmasked data should be available through that data source, and restrict which Grafana users or teams can query it; use separate data sources and IAM roles when viewers need different AWS access. See AWS guidance on viewing unmasked log data and Amazon Managed Grafana’s data-source query permissions. Cross-account observability also uses oam:ListSinks and oam:ListAttachedLinks for linked-account discovery; those actions are described below.
Grafana’s example IAM policies use Resource: "*" for these read actions. That is broad at the resource level: the role can query any metrics and log groups in the account and Regions allowed by its permissions. Where supported, narrow Logs Insights query access to the log-group ARNs the data source needs, and review AWS’s CloudWatch Logs action and resource reference before using a broader policy. The action list above does not grant metric or log write, delete, or configuration permissions. Amazon Managed Grafana’s AWS-managed CloudWatch policy also includes resource-discovery permissions; AWS recommends customer-managed policies when you need to reduce permissions to your use case.
Add the CloudWatch data source
- Sign in to Grafana with an organization administrator account. In the navigation, open Connections, choose Data sources or Add new connection, and select CloudWatch. Labels can vary by Grafana version.
- Choose the authentication provider for the deployment: the workspace role for Amazon Managed Grafana, AWS SDK Default for a self-hosted AWS runtime role, or Grafana Assume Role for Grafana Cloud.
- Set the Default Region to a Region where the role can read your data, such as
us-east-1. CloudWatch metrics and log groups are regional. The query editor also lets you choose a Region for a query, so one data source does not require a separate copy for every Region. - If using a target role, enter its Assume Role ARN. Supply an external ID only when the target role’s trust policy requires it; for Grafana Cloud, use the value displayed in the data source instructions.
- Choose Save & test. A healthy data-source check tests both metrics and logs. If the role intentionally has only one query type’s permissions, the combined check can report an error for the other type even though the permitted query type still works.
For an EC2, Lambda, or RDS dashboard, the CloudWatch data source also provides curated dashboards that you can import from its configuration page. Save a copy under a new name before customizing it, because a Grafana update can replace changes to an imported dashboard. See Grafana’s supported features and dashboard instructions.
Build and verify metrics and logs queries
Query a CloudWatch metric
In a new panel, choose the CloudWatch data source and CloudWatch Metrics. Select a Region, then try this EC2 CPU query:
- Namespace:
AWS/EC2 - Metric name:
CPUUtilization - Statistic:
Average - Dimension:
InstanceId= your EC2 instance ID
Choose a period that matches the metric resolution and the dashboard’s time range. If no series appears, verify that the instance emitted the metric in the selected Region and that the dimension exactly matches. Memory and filesystem metrics are not standard EC2 metrics; they require the CloudWatch agent to publish them.
Query CloudWatch Logs Insights
In a panel, select the CloudWatch data source and switch the query type to CloudWatch Logs. Choose the Region and a log group, then run this Logs Insights QL query. See the Grafana CloudWatch query editor guide for the query modes and editor fields:
fields @timestamp, @message
| filter @message like /ERROR/
| sort @timestamp desc
| limit 20The query returns the latest matching events from the selected time range. The like filter selects matching rows, but it does not reduce bytes scanned by itself. Reduce scan volume by narrowing the time range and selecting only the needed log groups. If you have created field indexes, equality or IN filters on indexed fields can skip events where possible; a like filter does not use those indexes. See AWS’s filter and field-index guidance. A result limit controls returned rows, not necessarily scanned bytes.
Access data in more than one account
There are two common patterns. With role assumption, the Grafana identity assumes a read role in each target account; this works across Regions supported by the data source. With CloudWatch cross-account observability, source accounts link selected metrics and log groups to a monitoring account through Observability Access Manager (OAM). OAM sharing is Region-specific and can expose only the telemetry types and namespaces or log groups that the accounts choose to share. Use role assumption for separate target-account roles or access outside an OAM link; use OAM when you want AWS to share selected CloudWatch data into a monitoring account. These are different access paths and can be used alongside one another.
For OAM discovery, grant oam:ListSinks and oam:ListAttachedLinks to the identity Grafana uses, along with the CloudWatch read permissions for the data it must query. The source and monitoring accounts must be linked in the same Region. Cross-account sharing for CloudWatch metrics and logs has no additional OAM charge, although the underlying CloudWatch features remain subject to their normal pricing. See AWS’s guides to using OAM with Amazon Managed Grafana and CloudWatch cross-account observability. For Amazon Managed Grafana workspaces in a VPC, AWS notes that OAM access needs a NAT gateway because OAM does not provide a VPC endpoint.
Control query costs and limits
Grafana queries CloudWatch; the integration does not make CloudWatch usage free. CloudWatch pricing depends on Region and on the metrics, logs, alarms, dashboards, and query features in use. Grafana uses ListMetrics to populate metric choices and GetMetricData to retrieve data. Grafana’s current documentation notes that GetMetricData requests do not qualify for the CloudWatch API free tier. CloudWatch Logs Insights charges are based on the uncompressed log data scanned by each query, as AWS explains in its Logs Insights query guide. Metrics Insights queries are priced by the number of metrics analyzed, so keep their filters selective as well. Check the CloudWatch pricing page for your Region and usage before deploying dashboards broadly.
- Set dashboard refresh intervals to the response time people need; every panel and refresh can generate more requests.
- Limit wide metric searches and use only the Regions, dimensions, and time ranges the dashboard needs. CloudWatch API quotas apply by account and Region.
- For Logs Insights, narrow the time window and selected log groups. Avoid frequent automatic refresh for expensive broad searches. A result limit reduces returned rows, not necessarily scanned bytes.
- Watch for API throttling and Logs Insights concurrency limits as dashboards, users, and alert evaluations grow. Check CloudWatch and CloudWatch Logs quotas for the account and Region, and request adjustments through AWS Service Quotas when needed.
CloudWatch alarms and dashboards have their own pricing. Grafana hosting is a separate cost if you use Amazon Managed Grafana, Grafana Cloud, or paid Grafana software. Review both services’ costs before choosing refresh intervals or adding many log-query panels.
Choose CloudWatch or Grafana alerting
A CloudWatch alarm is an AWS resource that evaluates a metric or supported query and can send notifications or invoke AWS actions when its state changes. It continues to evaluate even if Grafana is unavailable. Grafana can display CloudWatch alarm data when you grant the optional alarm-read actions in the permissions table.
Grafana alert rules evaluate queries through Grafana Alerting and can combine data from supported data sources. Use them when you want a Grafana-owned rule or a unified alert workflow. The evaluation and notification path then depends on Grafana being available and configured. The CloudWatch data source supports Grafana alerting; see Grafana-managed alert rules and AWS’s documentation on CloudWatch alarm actions. For threshold and evaluation-period design, see our CloudWatch alarms guide.
Troubleshoot common errors
| Symptom | What to check |
|---|---|
| Save & test fails but one query type works | The health check tests both metrics and logs. Check the matching query directly and either add the other feature’s permissions or accept that the combined check will report that feature as unavailable. |
AccessDenied or role-assumption failure | Confirm which role Grafana actually uses. For a role chain, check the source role’s sts:AssumeRole permission, the target role’s trust principal and external-ID condition, and the target role’s CloudWatch permissions. |
| No metric in the query editor | Check the Region, namespace, metric name, dimension values, and cloudwatch:ListMetrics. For custom metrics, add their namespace to the data source’s custom-metrics namespace setting. |
| Logs query returns no events | Confirm the Region and log group, widen the time range, verify the Logs Insights query syntax, and check logs:StartQuery, logs:GetQueryResults, and logs:DescribeLogGroups. |
| Timeout or throttling | Reduce the dashboard refresh rate and query breadth, check Grafana server logs, and verify outbound HTTPS access to the selected AWS service endpoints and STS when using role assumption. |
Grafana’s CloudWatch troubleshooting guide lists common permission, Region, timeout, and missing-metric causes. In particular, confirm that custom metric namespaces are configured and that the Grafana process can read the credentials provider you selected.
FAQs
Is CloudWatch built in to Grafana?
Yes. Current Grafana versions include the Amazon CloudWatch data source. Add and configure it in Grafana; no separate plugin installation is required.
What permissions does Grafana need for CloudWatch?
For metrics, grant cloudwatch:ListMetrics and cloudwatch:GetMetricData. For Logs Insights queries, grant logs:DescribeLogGroups, logs:StartQuery, logs:StopQuery, and logs:GetQueryResults. Add alarm, tag, EC2, OAM, raw-event, or unmask permissions only for the matching features.
Does Grafana replace CloudWatch alarms?
No. CloudWatch alarms are AWS resources with AWS alarm actions. Grafana alert rules are evaluated by Grafana and can combine supported data sources. Choose based on where you want the rule evaluated and what should happen when it fires.