AWS AmazonCloudWatch documentation change
Summary
Added documentation for querying via HTTP API, Grafana, and Amazon Managed Grafana. Updated endpoint references, simplified query examples, and included authentication/configuration details.
Security assessment
The changes add security documentation for SigV4 authentication and IAM permissions required for HTTP API access. While it enhances security awareness, there's no evidence of addressing a specific vulnerability.
Diff
diff --git a/AmazonCloudWatch/latest/monitoring/CloudWatch-PromQL-Querying.md b/AmazonCloudWatch/latest/monitoring/CloudWatch-PromQL-Querying.md index 12a696a23..5671b2c36 100644 --- a//AmazonCloudWatch/latest/monitoring/CloudWatch-PromQL-Querying.md +++ b//AmazonCloudWatch/latest/monitoring/CloudWatch-PromQL-Querying.md @@ -7 +7 @@ -Querying vended AWS metrics with PromQL +Querying vended AWS metrics with PromQLQuerying with the HTTP APIQuerying from GrafanaQuerying from Amazon Managed Grafana @@ -11 +11 @@ Querying vended AWS metrics with PromQL -When you ingest OpenTelemetry metrics into CloudWatch via OpenTelemetry Protocol (OTLP), the hierarchical OTLP data model is flattened into PromQL-compatible labels. This section describes the label structure, the PromQL syntax for querying these labels, and the UTF-8 support in PromQL. +When you ingest OpenTelemetry metrics into CloudWatch via the [Metrics endpoint](./CloudWatch-OTLPEndpoint.html#CloudWatch-MetricsEndpoint), the hierarchical OTLP data model is flattened into PromQL-compatible labels. This section describes the label structure, the PromQL syntax for querying these labels, and the UTF-8 support in PromQL. @@ -55 +55 @@ AWS-reserved | N/A | `@aws.` | `@aws.account_id="123456789"` -To be able to query vended AWS metrics in PromQL, you first need to enable OTel enrichment of vended metrics. See: [Enabling vended metrics in PromQL](./CloudWatch-OTelEnrichment.html). +To be able to query vended AWS metrics in PromQL, you first need to enable OTel enrichment of vended metrics. See: [AWS vended metrics in OpenTelemetry format](./CloudWatch-OTelEnrichment.html). @@ -76 +76 @@ The following example selects `Invocations` for a specific Lambda function: - histogram_sum({Invocations, FunctionName="my-api-handler"}) + {Invocations, FunctionName="my-api-handler"} @@ -81 +80,0 @@ The following example selects Lambda `Errors` for all functions tagged with a sp - histogram_sum( @@ -83 +81,0 @@ The following example selects Lambda `Errors` for all functions tagged with a sp - ) @@ -96,0 +95,109 @@ The following example selects all time series for the EC2 `CPUUtilization` metri +## Querying with the HTTP API + +In addition to CloudWatch Query Studio and PromQL alarms, you can query CloudWatch PromQL data programmatically through Prometheus-compatible HTTP endpoints. The supported operations are listed in [Prometheus-compatible APIs](./CloudWatch-PromQL-APIs.html). + +### Endpoint + +The PromQL endpoint follows the pattern `https://monitoring.`AWS Region`.amazonaws.com/api/v1/`operation``. For example, for the US East (N. Virginia) (us-east-1) Region, the endpoint for an instant query is `https://monitoring.us-east-1.amazonaws.com/api/v1/query`. + +For the list of AWS Regions where PromQL querying is available, see [Supported AWS Regions](./CloudWatch-PromQL.html#CloudWatch-PromQL-Regions). + +### Authentication + +The endpoint authenticates callers using Signature 4 authentication. For more information, see [AWS Signature Version 4 for API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). When you sign requests, use `monitoring` as the service name and the AWS Region of the request as the signing Region. + +For the IAM actions required for each operation, see [IAM permissions for PromQL](./CloudWatch-PromQL.html#CloudWatch-PromQL-IAM). + +### Sample query with awscurl + +The [awscurl](https://pypi.org/project/awscurl/) command-line tool signs HTTP requests with SigV4 using your AWS credentials, which makes it a convenient way to call the PromQL endpoints. Install it with `pip install awscurl`. + +The PromQL endpoints expect parameters in a form-encoded request body, so all of the following examples use `POST` with `-H 'Content-Type: application/x-www-form-urlencoded'`. Without that header, `awscurl` defaults to `application/json` and the server rejects the request. + +The following example evaluates an instant query against the US East (N. Virginia) (us-east-1) endpoint: + + + awscurl --service monitoring --region us-east-1 \ + -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/query' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'query=sum({"http.server.active_requests"})' + +A successful response uses the standard Prometheus JSON envelope: + + + { + "status": "success", + "data": { + "resultType": "vector", + "result": [ + { + "metric": {"__name__": "http.server.active_requests"}, + "value": [1780000000.000, "42"] + } + ] + } + } + +The following example lists the time series that match a selector by calling `/api/v1/series`. Series selectors support exact match (`=`), not equal (`!=`), regex match (`=~`), and negative regex match (`!~`) operators, identical to PromQL label matchers. The `start` and `end` parameters are required and bound the time range. + + + awscurl --service monitoring --region us-east-1 \ + -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/series' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'match[]={"http.server.active_requests","@resource.service.name"="myservice"}&start=1780662000&end=1780665600' + +The following example uses a regex match selector to find series for any service name that ends in `-api`: + + + awscurl --service monitoring --region us-east-1 \ + -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/series' \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d 'match[]={"http.server.active_requests","@resource.service.name"=~".*-api"}&start=1780662000&end=1780665600' + +The following example lists label names by calling `/api/v1/labels`: + + + awscurl --service monitoring --region us-east-1 \ + -X POST 'https://monitoring.us-east-1.amazonaws.com/api/v1/labels' \ + -H 'Content-Type: application/x-www-form-urlencoded' + +## Querying from Grafana + +You can 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/](https://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](./CloudWatch-PromQL.html#CloudWatch-PromQL-IAM). + +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. Choose **Save & test**. + + + + +## Querying from Amazon Managed Grafana + +You can query CloudWatch PromQL data from an Amazon Managed Grafana workspace by adding an **Amazon Managed Service for Prometheus** data source that points at the CloudWatch monitoring endpoint. 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](https://docs.aws.amazon.com/grafana/latest/userguide/amazon-prometheus-data-source.html) 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](./CloudWatch-PromQL.html#CloudWatch-PromQL-IAM). + +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. Choose **Save & test**. + + + + @@ -105 +212 @@ Query metrics with PromQL -Running PromQL queries in Query Studio (Preview) +Running PromQL queries in Query Studio