View a markdown version of this page

Grafana integration - Amazon CloudWatch
Querying with the CloudWatch data sourceQuerying from Grafana with the Amazon Managed Service for Prometheus data sourceQuerying from Amazon Managed Grafana with the Amazon Managed Service for Prometheus data source

Grafana integration

After you ingest OpenTelemetry metrics into CloudWatch and make them queryable with PromQL, you can visualize and explore that data in Grafana and Amazon Managed Grafana. We recommend that you use the PromQL query type in the Amazon CloudWatch data source plugin. It uses the same authentication and Region settings as your other CloudWatch queries, so you don't need to configure a separate data source. For more information, see Querying with the CloudWatch data source.

Alternatively, you can connect to the CloudWatch monitoring endpoint through the Amazon Managed Service for Prometheus data source plugin, which signs requests with Signature Version 4 (SigV4). Use this option if your Grafana version or Amazon Managed Grafana workspace doesn't support the PromQL query type in the CloudWatch data source. For more information, see Querying from Grafana with the Amazon Managed Service for Prometheus data source and Querying from Amazon Managed Grafana with the Amazon Managed Service for Prometheus data source.

Querying with the CloudWatch data source

The Amazon CloudWatch data source plugin includes a PromQL query type, alongside the Metric Search and Metric Insights query types. The plugin sends SigV4-signed requests to the CloudWatch PromQL endpoint for the selected Region. You don't need to change the data source configuration or set a signing service.

The PromQL query type is available in the following environments:

  • Amazon Managed Grafana — workspaces that use Grafana version 13 or later. For more information, see Grafana version 13 in the Amazon Managed Grafana User Guide.

  • Grafana — version 12.10.0 or later of the CloudWatch data source plugin, which includes both the Builder and Code editing modes. The plugin requires Grafana >=11.6.11 <12 || >=12.0.10 <12.1 || >=12.1.7 <12.2 || >=12.2.5. To update the plugin, use the Grafana plugins catalog.

IAM prerequisites — the IAM principal that the CloudWatch data source uses, such as the Amazon Managed Grafana workspace IAM role, must have both cloudwatch:GetMetricData (required for instant and range queries) and cloudwatch:ListMetrics (required for metric, label key, and label value autocomplete). For details, see IAM permissions for PromQL.

Note

If the IAM principal has only these permissions, choosing Save & test on the CloudWatch data source reports an error for the CloudWatch Logs check because it can't call logs:DescribeLogGroups. The metrics check still succeeds, and PromQL queries aren't affected. To clear the error, also grant the permissions that the CloudWatch data source needs for logs queries.

To query CloudWatch metrics with PromQL, complete the following steps.

  1. Add an Amazon CloudWatch data source, or use an existing one. In Amazon Managed Grafana, you can use the AWS data source configuration option to add the data source and manage its credentials. For more information, see Connect to an Amazon CloudWatch data source in the Amazon Managed Grafana User Guide.

  2. In a dashboard panel or in Explore, select the CloudWatch data source.

  3. In the query editor, choose PromQL as the query type.

  4. For Region, keep the data source default or choose the AWS Region that contains your OpenTelemetry metrics.

  5. Build the query in one of the following editing modes. Use the Builder/Code toggle to switch between them.

    • Builder — select a metric, add label filters, and optionally add operations such as aggregations and functions.

    • Code — enter a PromQL expression directly. The editor suggests metric names, label keys, and label values. To build a selector visually, choose Metrics browser.

  6. (Optional) Under the query options, set Legend, Min step, Format (Time series or Table), and Type (Range or Instant).

Querying from Grafana with the Amazon Managed Service for Prometheus data source

You can also query CloudWatch PromQL data from Grafana by adding the Amazon Managed Service for Prometheus data source plugin and pointing it at the CloudWatch monitoring endpoint. SigV4 signing is built in to the plugin and is always enabled, so there is no toggle to turn on. The plugin is published at grafana.com/grafana/plugins/grafana-amazonprometheus-datasource/; install it from the Grafana plugins catalog before adding the data source. AMP plugin v3.0.0 requires Grafana >=11.6.11 <12 || >=12.0.10 <12.1 || >=12.1.7 <12.2 || >=12.2.5.

IAM prerequisites — the IAM principal whose credentials Grafana uses must have both cloudwatch:GetMetricData (required for instant and range queries) and cloudwatch:ListMetrics (required for series and label discovery). For details, see IAM permissions for PromQL.

To configure Grafana, complete the following steps.

  1. Install the Amazon Managed Service for Prometheus data source plugin from the Grafana plugins catalog.

  2. In Grafana, go to Connections, Data sources, choose Add data source, and select Amazon Managed Service for Prometheus.

  3. Set the data source URL to https://monitoring.AWS Region.amazonaws.com.

  4. Set the Region to your AWS Region. Choose an Authentication provider appropriate for your environment (default credential chain, access keys, or workspace IAM role).

  5. Set the Service field to monitoring. The plugin defaults this field to aps for Amazon Managed Service for Prometheus, but the CloudWatch PromQL endpoint requires monitoring.

  6. Choose Save & test.

Important

Service must be set to monitoring

If you leave Service at the default value aps, every query fails with HTTP 403. The response includes the message Credential should be scoped to correct service: 'monitoring'. When you provision the data source as YAML or Terraform, set the equivalent key sigv4Service to monitoring.

Querying from Amazon Managed Grafana with the Amazon Managed Service for Prometheus data source

If your Amazon Managed Grafana workspace uses Grafana version 12, you can query CloudWatch PromQL data by adding an Amazon Managed Service for Prometheus data source that points at the CloudWatch monitoring endpoint. For workspaces that use Grafana version 13 or later, we recommend the CloudWatch data source instead. For more information, see Querying with the CloudWatch data source.

This data source plugin signs requests with SigV4 using the workspace IAM role automatically; SigV4 is always enabled, with no toggle to configure. The plugin is available in Amazon Managed Grafana version 12 and later. For more information, see Connect to an Amazon Managed Service for Prometheus data source in the Amazon Managed Grafana User Guide.

IAM prerequisites — the Amazon Managed Grafana workspace IAM role must have both cloudwatch:GetMetricData (required for instant and range queries) and cloudwatch:ListMetrics (required for series and label discovery). For details, see IAM permissions for PromQL.

To configure the data source, complete the following steps.

  1. In your Amazon Managed Grafana workspace, add an Amazon Managed Service for Prometheus data source.

  2. Set the data source URL to https://monitoring.AWS Region.amazonaws.com.

  3. Set the Region to your AWS Region. Amazon Managed Grafana injects credentials from the workspace IAM role automatically; you do not need to configure static keys.

  4. Set the Service field to monitoring. The plugin defaults this field to aps, but the CloudWatch PromQL endpoint requires monitoring.

  5. Choose Save & test.