AWS Security ChangesHomeSearch

AWS AmazonCloudWatch: Rework Prometheus EC2 scraping guide with prerequisites

Service: AmazonCloudWatch · 2026-11-21 · Documentation medium

File: AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-PrometheusEC2.md · Type: iam

Summary

Rewrites the CloudWatch agent Prometheus EC2 documentation around the OpenTelemetry/OTLP flow, adds prerequisite guidance for security groups and the ec2:DescribeInstances IAM permission, and updates scrape configuration and JMX examples.

Security assessment

The change adds least-privilege IAM and network access prerequisites for EC2 Prometheus service discovery, which is security hardening guidance rather than evidence of a specific vulnerability or incident.

Evidence

+  * If you use `ec2_sd_configs` to discover targets, the IAM role of the instance where the agent runs must allow `ec2:DescribeInstances`.

Diff

diff --git a/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-PrometheusEC2.md b/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-PrometheusEC2.md
index 161af3c..abea94d 100644
--- a//AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-PrometheusEC2.md
+++ b//AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-PrometheusEC2.md
@@ -7 +7 @@
-Step 1: Install the CloudWatch agentStep 2: Scrape Prometheus sources and import metricsExample: Set up Java/JMX sample workloads for Prometheus metric testing
+PrerequisitesCreating the Prometheus scrape configurationConfiguring and starting the agentExample: Scrape JVM metrics with the Prometheus JMX exporter
@@ -9 +9 @@ Step 1: Install the CloudWatch agentStep 2: Scrape Prometheus sources and import
-# Set up and configure Prometheus metrics collection on Amazon EC2 instances
+# Scrape Prometheus metrics on Amazon EC2 instances
@@ -11 +11 @@ Step 1: Install the CloudWatch agentStep 2: Scrape Prometheus sources and import
-The following sections explain how to install the CloudWatch agent with Prometheus monitoring on EC2 instances, and how to configure the agent to scrape additional targets. It also provides tutorials for setting up sample workloads to use testing with Prometheus monitoring.
+The CloudWatch agent can scrape applications that expose metrics in the Prometheus format and send the metrics to the CloudWatch OTLP endpoint. You can then query the metrics with PromQL. Both Linux and Windows Server instances are supported.
@@ -13 +13 @@ The following sections explain how to install the CloudWatch agent with Promethe
-Both Linux and Windows instances are supported.
+To scrape Prometheus metrics, you need two files: a standard Prometheus scrape configuration file, and a CloudWatch agent configuration file whose `opentelemetry` section has a `prometheus` source that points to the scrape configuration file.
@@ -15,7 +15 @@ Both Linux and Windows instances are supported.
-For information about the operating systems supported by the CloudWatch agent, see [Collect metrics, logs, and traces using the CloudWatch agent](./Install-CloudWatch-Agent.html)
-
-**VPC security group requirements**
-
-If you are using a VPC, the following requirements apply.
-
-  * The ingress rules of the security groups for the Prometheus workloads must open the Prometheus ports to the CloudWatch agent for scraping the Prometheus metrics by the private IP.
+## Topics
@@ -23 +17 @@ If you are using a VPC, the following requirements apply.
-  * The egress rules of the security group for the CloudWatch agent must allow the CloudWatch agent to connect to the Prometheus workloads' port by private IP. 
+  * Prerequisites
@@ -24,0 +19 @@ If you are using a VPC, the following requirements apply.
+  * Creating the Prometheus scrape configuration
@@ -25,0 +21 @@ If you are using a VPC, the following requirements apply.
+  * Configuring and starting the agent
@@ -26,0 +23 @@ If you are using a VPC, the following requirements apply.
+  * Example: Scrape JVM metrics with the Prometheus JMX exporter
@@ -28 +24,0 @@ If you are using a VPC, the following requirements apply.
-## Topics
@@ -30 +25,0 @@ If you are using a VPC, the following requirements apply.
-  * Step 1: Install the CloudWatch agent
@@ -32 +26,0 @@ If you are using a VPC, the following requirements apply.
-  * Step 2: Scrape Prometheus sources and import metrics
@@ -34 +28 @@ If you are using a VPC, the following requirements apply.
-  * Example: Set up Java/JMX sample workloads for Prometheus metric testing
+## Prerequisites
@@ -35,0 +30 @@ If you are using a VPC, the following requirements apply.
+  * Install CloudWatch agent version 1.300070.0 or later on the instance. For more information, see [Prerequisites](./CloudWatch-Agent-OpenTelemetry-config.html#CloudWatch-Agent-OpenTelemetry-config-prereqs).
@@ -36,0 +32 @@ If you are using a VPC, the following requirements apply.
+  * If the agent scrapes other instances, the security groups of those instances must allow inbound traffic on the Prometheus port from the agent's private IP address. The agent's security group must allow outbound traffic to that port.
@@ -37,0 +34 @@ If you are using a VPC, the following requirements apply.
+  * If you use `ec2_sd_configs` to discover targets, the IAM role of the instance where the agent runs must allow `ec2:DescribeInstances`.
@@ -39 +35,0 @@ If you are using a VPC, the following requirements apply.
-## Step 1: Install the CloudWatch agent
@@ -41 +36,0 @@ If you are using a VPC, the following requirements apply.
-The first step is to install the CloudWatch agent on the EC2 instance. For instructions, see [Installing the CloudWatch agent](./install-CloudWatch-Agent-on-EC2-Instance.html).
@@ -43 +37,0 @@ The first step is to install the CloudWatch agent on the EC2 instance. For instr
-## Step 2: Scrape Prometheus sources and import metrics
@@ -45 +39 @@ The first step is to install the CloudWatch agent on the EC2 instance. For instr
-The CloudWatch agent with Prometheus monitoring needs two configurations to scrape the Prometheus metrics. One is for the standard Prometheus configurations as documented in [ <scrape_config>](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config)in the Prometheus documentation. The other is for the CloudWatch agent configuration.
+## Creating the Prometheus scrape configuration
@@ -47 +41 @@ The CloudWatch agent with Prometheus monitoring needs two configurations to scra
-### Prometheus scrape configuration
+The agent supports the standard Prometheus scrape configuration. For more information about the scrape configuration, see [<scrape_config>](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) on the Prometheus website. Save the file in the agent's `etc` directory, for example `/opt/aws/amazon-cloudwatch-agent/etc/prometheus.yaml` on Linux or `C:\ProgramData\Amazon\AmazonCloudWatchAgent\prometheus.yaml` on Windows Server.
@@ -49 +43 @@ The CloudWatch agent with Prometheus monitoring needs two configurations to scra
-The CloudWatch agent supports the standard Prometheus scrape configurations as documented in [ <scrape_config>](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) in the Prometheus documentation. You can edit this section to update the configurations that are already in this file, and add additional Prometheus scraping targets. A sample configuration file contains the following global configuration lines:
+The following example scrapes a local application every minute:
@@ -52 +45,0 @@ The CloudWatch agent supports the standard Prometheus scrape configurations as d
-    PS C:\ProgramData\Amazon\AmazonCloudWatchAgent> cat prometheus.yaml
@@ -57 +50 @@ The CloudWatch agent supports the standard Prometheus scrape configurations as d
-    - job_name: MY_JOB
+      - job_name: my-app
@@ -59,11 +52,4 @@ The CloudWatch agent supports the standard Prometheus scrape configurations as d
-      file_sd_configs:
-        - files: ["C:\\ProgramData\\Amazon\\AmazonCloudWatchAgent\\prometheus_sd_1.yaml", "C:\\ProgramData\\Amazon\\AmazonCloudWatchAgent\\prometheus_sd_2.yaml"]
-
-The `global` section specifies parameters that are valid in all configuration contexts. They also serve as defaults for other configuration sections. It contains the following parameters:
-
-  * `scrape_interval`— Defines how frequently to scrape targets.
-
-  * `scrape_timeout`— Defines how long to wait before a scrape request times out.
-
-
-
+        static_configs:
+          - targets: ['127.0.0.1:9404']
+            labels:
+              team: payments
@@ -71 +57 @@ The `global` section specifies parameters that are valid in all configuration co
-The `scrape_configs` section specifies a set of targets and parameters that define how to scrape them. It contains the following parameters:
+The file contains the following sections:
@@ -73 +59 @@ The `scrape_configs` section specifies a set of targets and parameters that defi
-  * `job_name`— The job name assigned to scraped metrics by default.
+  * `global` – Defaults for all scrape jobs. `scrape_interval` sets how often to scrape targets, and `scrape_timeout` sets how long to wait before a scrape request times out.
@@ -75 +61 @@ The `scrape_configs` section specifies a set of targets and parameters that defi
-  * `sample_limit`— Per-scrape limit on the number of scraped samples that will be accepted.
+  * `scrape_configs` – One entry for each scrape job. `job_name` names the job. The agent sets the `@resource.service.name` label on the scraped metrics to this value. `sample_limit` limits the number of samples that the agent accepts from each scrape.
@@ -77 +62,0 @@ The `scrape_configs` section specifies a set of targets and parameters that defi
-  * `file_sd_configs`— List of file service discovery configurations. It reads a set of files containing a list of zero or more static configs. The `file_sd_configs` section contains a `files` parameter which defines patterns for files from which target groups are extracted.
@@ -80,0 +66 @@ The `scrape_configs` section specifies a set of targets and parameters that defi
+To tell the agent which targets to scrape, use one of the following service discovery types in each job:
@@ -82 +68 @@ The `scrape_configs` section specifies a set of targets and parameters that defi
-The CloudWatch agent supports the following service discovery configuration types.
+  * `static_configs` – A fixed list of targets, and labels to add to all metrics from those targets, as in the previous example.
@@ -84 +70 @@ The CloudWatch agent supports the following service discovery configuration type
-**`static_config`** Allows specifying a list of targets and a common label set for them. It is the canonical way to specify static targets in a scrape configuration.
+  * `file_sd_configs` – Reads targets from one or more files. The agent rereads the files when they change, so you can update targets without restarting the agent.
@@ -86 +72,4 @@ The CloudWatch agent supports the following service discovery configuration type
-The following is a sample static config to scrape Prometheus metrics from a local host. Metrics can also be scraped from other servers if the Prometheus port is open to the server where the agent runs.
+        scrape_configs:
+      - job_name: my-app
+        file_sd_configs:
+          - files: ['/opt/aws/amazon-cloudwatch-agent/etc/prometheus_sd_1.yaml']
@@ -87,0 +77 @@ The following is a sample static config to scrape Prometheus metrics from a loca
+Each file lists targets and labels:
@@ -89 +78,0 @@ The following is a sample static config to scrape Prometheus metrics from a loca
-    PS C:\ProgramData\Amazon\AmazonCloudWatchAgent> cat prometheus_sd_1.yaml
@@ -93,11 +82 @@ The following is a sample static config to scrape Prometheus metrics from a loca
-        key1: value1
-        key2: value2
-
-This example contains the following parameters:
-
-  * `targets`— The targets scraped by the static config.
-
-  * `labels`— Labels assigned to all metrics that are scraped from the targets.
-
-
-
+        team: payments
@@ -105 +84 @@ This example contains the following parameters:
-**`ec2_sd_config`** Allows retrieving scrape targets from Amazon EC2 instances. The following is a sample `ec2_sd_config` to scrape Prometheus metrics from a list of EC2 instances. The Prometheus ports of these instances have to open to the server where the CloudWatch agent runs. The IAM role for the EC2 instance where the CloudWatch agent runs must include the `ec2:DescribeInstance` permission. For example, you could attach the managed policy **AmazonEC2ReadOnlyAccess** to the instance running the CloudWatch agent.
+  * `ec2_sd_configs` – Discovers targets from the Amazon EC2 API. The following example scrapes port 9404 on two instances. If you omit `region`, the agent uses the Region from the instance metadata.
@@ -107,5 +85,0 @@ This example contains the following parameters:
-    
-    PS C:\ProgramData\Amazon\AmazonCloudWatchAgent> cat prometheus.yaml
-    global:
-      scrape_interval: 1m
-      scrape_timeout: 10s
@@ -113,2 +87 @@ This example contains the following parameters:
-      - job_name: MY_JOB
-        sample_limit: 10000
+      - job_name: my-app
@@ -124,28 +97 @@ This example contains the following parameters:
-This example contains the following parameters:
-
-  * `region`— The AWS Region where the target EC2 instance is. If you leave this blank, the Region from the instance metadata is used.
-
-  * `port`— The port to scrape metrics from.
-
-  * `filters`— Optional filters to use to filter the instance list. This example filters based on EC2 instance IDs. For more criteria that you can filter on, see [ DescribeInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html).
-
-
-
-
-### CloudWatch agent configuration for Prometheus
-
-The CloudWatch agent configuration file includes `prometheus` sections under both `logs` and `metrics_collected`. It includes the following parameters.
-
-  * **cluster_name** — specifies the cluster name to be added as a label in the log event. This field is optional. 
-
-  * **log_group_name** — specifies the log group name for the scraped Prometheus metrics.
-
-  * **prometheus_config_path** — specifies the Prometheus scrape configuration file path.
-
-  * **emf_processor** — specifies the embedded metric format processor configuration. For more information about embedded metric format, see [Embedding metrics within logs](./CloudWatch_Embedded_Metric_Format.html). 
-
-The `emf_processor` section can contain the following parameters:
-
-    * **metric_declaration_dedup** — It set to true, the de-duplication function for the embedded metric format metrics is enabled.
-
-    * **metric_namespace** — Specifies the metric namespace for the emitted CloudWatch metrics.
+For more information about the filters that you can use, see [DescribeInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html) in the _Amazon EC2 API Reference_.
@@ -153 +98,0 @@ The `emf_processor` section can contain the following parameters:
-    * **metric_unit** — Specifies the metric name:metric unit map. For information about supported metric units, see [ MetricDatum](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html).
@@ -155 +99,0 @@ The `emf_processor` section can contain the following parameters:
-    * **metric_declaration** — are sections that specify the array of logs with embedded metric format to be generated. There are `metric_declaration` sections for each Prometheus source that the CloudWatch agent imports from by default. These sections each include the following fields:
@@ -157 +100,0 @@ The `emf_processor` section can contain the following parameters:
-      * `source_labels` specifies the value of the labels that are checked by the `label_matcher` line.
@@ -159,10 +102 @@ The `emf_processor` section can contain the following parameters:
-      * `label_matcher` is a regular expression that checks the value of the labels listed in `source_labels`. The metrics that match are enabled for inclusion in the embedded metric format sent to CloudWatch. 
-
-      * `metric_selectors` is a regular expression that specifies the metrics to be collected and sent to CloudWatch.
-
-      * `dimensions` is the list of labels to be used as CloudWatch dimensions for each selected metric.
-
-
-
-
-The following is an example CloudWatch agent configuration for Prometheus.
+## Configuring and starting the agent
@@ -169,0 +104 @@ The following is an example CloudWatch agent configuration for Prometheus.
+  1. In the agent configuration file, add a `prometheus` source to the `opentelemetry` section, and set `config_path` to the scrape configuration file.
@@ -172,2 +107,3 @@ The following is an example CloudWatch agent configuration for Prometheus.
-       "logs":{
-          "metrics_collected":{
+      "opentelemetry": {
+        "collect": {
+          "host_metrics": {},
@@ -175,32 +111 @@ The following is an example CloudWatch agent configuration for Prometheus.
-                "cluster_name":"prometheus-cluster",
-                "log_group_name":"Prometheus",
-                "prometheus_config_path":"C:\\ProgramData\\Amazon\\AmazonCloudWatchAgent\\prometheus.yaml",