AWS Security ChangesHomeSearch

AWS AmazonCloudWatch: CloudWatch agent config reference restructure; OTel section moved out

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

File: AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.md

Summary

Editorial reorganization of the CloudWatch agent configuration file reference: renames Classic sections (metrics/logs/traces), relabels the `otlp` links as 'Classic configuration (legacy)', moves the entire `opentelemetry` section (including OTLP receiver endpoints, files, windows_events, host_metrics, prometheus fields) to a dedicated page, removes the legacy `emf` field documentation, updates JSON examples, and deletes the 'Save the CloudWatch agent configuration file manually' section. No security behavior or guidance is added or changed.

Security assessment

The only security-adjacent content is the removed OTLP listener guidance (binding to 0.0.0.0:4317/4318 in containers), but it is deleted as part of relocating the `opentelemetry` section to another page, not as a fix for a vulnerability or exposure issue. All other edits are link/label/example cleanups and section renames with no auth, encryption, IAM, or logging-security impact.

Evidence

-      * `grpc_endpoint` – Optional. Specifies the address the agent uses to listen for OTLP data sent using gRPC. The format is `ip:port`. This address must match the address set for the gRPC exporter in the OpenTelemetry SDK. If you omit this field, the agent uses the default `127.0.0.1:4317`. In a containerized deployment, set this to `0.0.0.0:4317` so the agent accepts traffic from other pods.

Diff

diff --git a/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.md b/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.md
index 357e62d..f1e956b 100644
--- a//AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.md
+++ b//AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.md
@@ -7 +7 @@
-Save the agent configuration file manuallyUpdate the agent configuration file manuallyUpload the CloudWatch agent configuration file to Systems Manager Parameter Store
+Update the agent configuration file manuallyUpload the CloudWatch agent configuration file to Systems Manager Parameter Store
@@ -13 +13 @@ The CloudWatch agent configuration file is a JSON file with five sections: `agen
-  * The `agent` section includes fields for the overall configuration of the agent. 
+  * The `agent` section includes fields for the overall configuration of the agent. It applies to both configuration models.
@@ -15 +15 @@ The CloudWatch agent configuration file is a JSON file with five sections: `agen
-  * The `metrics` section specifies the custom metrics for collection and publishing to CloudWatch. If you're using the agent only to collect logs, you can omit the `metrics` section from the file.
+  * The `metrics` section (Classic) specifies the custom metrics for collection and publishing to CloudWatch. If you're using the agent only to collect logs, you can omit the `metrics` section from the file.
@@ -17 +17 @@ The CloudWatch agent configuration file is a JSON file with five sections: `agen
-  * The `logs` section specifies what log files are published to CloudWatch Logs. This can include events from the Windows Event Log if the server runs Windows Server.
+  * The `logs` section (Classic) specifies what log files are published to CloudWatch Logs. This can include events from the Windows Event Log if the server runs Windows Server.
@@ -19 +19 @@ The CloudWatch agent configuration file is a JSON file with five sections: `agen
-  * The `traces` section specifies the sources for traces that are collected and sent to AWS X-Ray. 
+  * The `traces` section (Classic) specifies the sources for traces that are collected and sent to AWS X-Ray. 
@@ -21 +21 @@ The CloudWatch agent configuration file is a JSON file with five sections: `agen
-  * The `opentelemetry` section specifies the sources of metrics, logs, and traces for the agent to collect and send to the CloudWatch OpenTelemetry Protocol (OTLP) endpoints. For more information, see [OTLP Endpoints](./CloudWatch-OTLPEndpoint.html).
+  * The `opentelemetry` section specifies the sources of metrics, logs, and traces for the agent to collect and send to the CloudWatch OpenTelemetry Protocol (OTLP) endpoints. For the field reference, see [CloudWatch agent configuration file: OpenTelemetry section](./CloudWatch-Agent-Configuration-File-OpenTelemetrysection.html).
@@ -56 +56 @@ If you are monitoring an on-premises server, this field isn't used, and the agen
-  * `aws_sdk_log_level` – Optional. Supported only in versions 1.247350.0 and later of the CloudWatch agent.
+  * `aws_sdk_log_level` – Optional.
@@ -70,2 +69,0 @@ You can specify this field to have the agent perform logging for AWS SDK endpoin
-For more information about these options, see [LogLevelType](https://docs.aws.amazon.com/sdk-for-go/api/aws/#LogLevelType).
-
@@ -173,0 +172,5 @@ The contents of the `metrics_collected` section depend on whether this configura
+        "metrics_collected": {
+          "cpu": {
+            "measurement": ["usage_active"]
+          }
+        },
@@ -426 +429 @@ Within the entry for each individual metric, you can optionally specify one or b
-  * `otlp` – Optional. Specifies that you want to collect metrics from the OpenTelemetry SDK. For more information about the fields that you can use in this section, see [Collect metrics and traces with OpenTelemetry](./CloudWatch-Agent-OpenTelemetry-metrics.html). 
+  * `otlp` – Optional. Specifies that you want to collect metrics from the OpenTelemetry SDK. For more information about the fields that you can use in this section, see [Receive OTLP data with the Classic configuration (legacy)](./CloudWatch-Agent-OpenTelemetry-metrics.html). 
@@ -556 +559 @@ There are other optional sections that you can include in `metrics_collected`:
-  * `otlp` – Optional. Specifies that you want to collect metrics from the OpenTelemetry SDK. For more information about the fields that you can use in this section, see [Collect metrics and traces with OpenTelemetry](./CloudWatch-Agent-OpenTelemetry-metrics.html). 
+  * `otlp` – Optional. Specifies that you want to collect metrics from the OpenTelemetry SDK. For more information about the fields that you can use in this section, see [Receive OTLP data with the Classic configuration (legacy)](./CloudWatch-Agent-OpenTelemetry-metrics.html). 
@@ -774 +777 @@ If a single log entry contains two time stamps that match the format, the first
-This list of symbols is different than the list used by the older CloudWatch Logs agent. For a summary of these differences, see [Timestamp differences between the CloudWatch agent and the earlier CloudWatch Logs agent](./CloudWatch-Agent-common-scenarios.html#CloudWatch-Agent-logs-timestamp-differences)
+The agent supports the following symbols:
@@ -1160,2 +1162,0 @@ For example, the following part of the logs section of the configuration file se
-If you are using the agent to report high-resolution metrics in embedded metric format, and you are setting alarms on those metrics, keep this parameter set to the default value of 5. Otherwise, the metrics are reported with a delay that can cause alarming on partial or incomplete data.
-
@@ -1166 +1167 @@ If you are using the agent to report high-resolution metrics in embedded metric
-  * `metrics_collected` – This field can contain sections to specify that the agent is to collect logs to enable use cases such as CloudWatch Application Signals and Container Insights with enhanced observability for Amazon EKS.
+  * `metrics_collected` – Turns on CloudWatch Application Signals and Container Insights with enhanced observability for Amazon EKS. This field can contain the following sections.
@@ -1172 +1173 @@ If you are using the agent to report high-resolution metrics in embedded metric
-      * `enhanced_container_insights` – Set this to `true` to enable Container Insights with enhanced observability for Amazon EKS. For more information, see [Amazon EKS](./deploy-container-insights-EKS.html).
+      * `enhanced_container_insights` – Set this to `true` to enable Container Insights with enhanced observability for Amazon EKS. For more information, see [Container Insights for Amazon EKS](./ContainerInsights.html).
@@ -1176,4 +1176,0 @@ If you are using the agent to report high-resolution metrics in embedded metric
-    * `emf` – To collect metrics embedded in logs, it is no longer necessary to add this `emf` field. This is a legacy field that specified that the agent is to collect logs that are in embedded metric format. You can generate metric data from these logs. For more information, see [Embedding metrics within logs](./CloudWatch_Embedded_Metric_Format.html).
-
-    * `otlp` – Optional. Specifies that you want to collect metrics from the OpenTelemetry SDK. For more information about the fields that you can use in this section, see [Collect metrics and traces with OpenTelemetry](./CloudWatch-Agent-OpenTelemetry-metrics.html).
-
@@ -1238,6 +1235 @@ The following is an example of a `logs` section.
-           "log_stream_name": "my_log_stream_name",
-           "metrics_collected": {
-            "kubernetes": {
-            "enhanced_container_insights": true
-          }
-        }
+           "log_stream_name": "my_log_stream_name"
@@ -1298 +1290 @@ If you omit this field, the default of `127.0.0.1:2000` is used.
-    * `otlp` – Optional. Specifies that you want to collect traces from the OpenTelemetry SDK. For more information about the fields that you can use in this section, see [Collect metrics and traces with OpenTelemetry](./CloudWatch-Agent-OpenTelemetry-metrics.html)). For more information about the AWS Distro for OpenTelemetry, see [AWS Distro for OpenTelemetry](https://aws.amazon.com/otel/). For more information about the AWS Distro for OpenTelemetry SDKs, see [Introduction](https://aws-otel.github.io/docs/introduction).
+    * `otlp` – Optional. Specifies that you want to collect traces from the OpenTelemetry SDK. For more information about the fields that you can use in this section, see [Receive OTLP data with the Classic configuration (legacy)](./CloudWatch-Agent-OpenTelemetry-metrics.html)). For more information about the AWS Distro for OpenTelemetry, see [AWS Distro for OpenTelemetry](https://aws.amazon.com/otel/). For more information about the AWS Distro for OpenTelemetry SDKs, see [Introduction](https://aws-otel.github.io/docs/introduction).
@@ -1333,95 +1324,0 @@ If you specify a Region here, it takes precedence over the setting of the `regio
-The `opentelemetry` section depends on the agent's OTLP receiver, which was introduced in CloudWatch agent version 1.300070.0. Earlier versions do not support it. To check the installed version, read `/opt/aws/amazon-cloudwatch-agent/bin/CWAGENT_VERSION`.
-
-Note
-
-On Amazon Linux 2023, the `yum install amazon-cloudwatch-agent` and `dnf install amazon-cloudwatch-agent` commands install a version that meets this minimum. If your package repository offers a version earlier than 1.300070.0, install the agent from the CloudWatch agent download instead. For more information, see [Collect metrics, logs, and traces using the CloudWatch agent](./Install-CloudWatch-Agent.html).
-
-The `opentelemetry` section can include the following fields:
-
-  * `cluster_name` – Optional. Specifies the name of the Kubernetes cluster. The agent applies this value to all telemetry collected under the `opentelemetry` section.
-
-  * `resource_attributes` – Optional. Specifies additional resource attributes to add to every metric, log, and trace collected under the `opentelemetry` section. This field is an object of string key-value pairs. You can specify up to 30 attributes. The maximum length of each value is 1024 characters. For attributes that the agent detects automatically, such as `cloud.region`, `host.id`, and `cloud.provider`, the detected value takes precedence. Use this field for attributes that the agent does not detect on its own.
-
-  * `collect` – Required. Specifies which telemetry sources the agent collects. You must include at least one of the following fields:
-
-    * `otlp` – Optional. Specifies that the agent receives metrics, traces, and logs sent to it over the OpenTelemetry Protocol (OTLP). This section can include the following fields:
-
-      * `grpc_endpoint` – Optional. Specifies the address the agent uses to listen for OTLP data sent using gRPC. The format is `ip:port`. This address must match the address set for the gRPC exporter in the OpenTelemetry SDK. If you omit this field, the agent uses the default `127.0.0.1:4317`. In a containerized deployment, set this to `0.0.0.0:4317` so the agent accepts traffic from other pods.
-
-      * `http_endpoint` – Optional. Specifies the address the agent uses to listen for OTLP data sent over HTTP. The format is `ip:port`. This address must match the address set for the HTTP exporter in the OpenTelemetry SDK. If you omit this field, the agent uses the default `127.0.0.1:4318`. In a containerized deployment, set this to `0.0.0.0:4318` so the agent accepts traffic from other pods.
-
-      * `span_metrics_enabled` – Optional. If `true`, the agent derives request, error, and duration metrics from received traces. The default value is `false`.
-
-    * `files` – Optional. Specifies that the agent collects log files from the host. It contains one field, `collect_list`.
-
-      * `collect_list` – Required if `files` is included. Contains an array of entries, each of which specifies one set of log files to collect. The array must contain at least one entry. Each entry can include the following fields:
-
-        * `file_path` – Required. Specifies the path or glob pattern of the log files to collect. The maximum length is 4096 characters.
-
-        * `log_group_name` – Optional. Specifies the log group name to use in CloudWatch Logs. The maximum length is 512 characters. You can use `{instance_id}`, `{hostname}`, `{local_hostname}`, and `{ip_address}` as variables within the name. If you omit this field, the agent uses `/aws/cwagent/files`. On Kubernetes, the agent includes the cluster name, as in `/aws/cwagent/{cluster_name}/files`.
-
-        * `log_stream_name` – Optional. Specifies the log stream name to use in CloudWatch Logs. The maximum length is 512 characters. This field supports the same variables as `log_group_name`. If you omit this field, the agent uses the host identifier and the log file name, separated by a slash (for example, `i-0123456789abcdef0/app.log`).
-
-        * `multi_line_start_pattern` – Optional. Specifies a regular expression that marks the start of a new log entry. The agent appends lines that don't match the pattern to the previous entry. Specify the value `{timestamp_format}` to derive the pattern from `timestamp_format`.
-
-        * `timestamp_format` – Optional. Specifies the format used to parse timestamps from log lines. For example, `%Y-%m-%d %H:%M:%S`.
-
-        * `timezone` – Optional. Specifies the time zone to use when parsing timestamps. Valid values are `UTC` and `Local`. The default value is `Local`.
-
-        * `encoding` – Optional. Specifies the encoding of the log files. If you omit this field, the agent uses the default `utf-8`.
-
-    * `windows_events` – Optional. Specifies that the agent collects events from the Windows Event Log. This source is available only on servers running Windows Server. It contains one field, `collect_list`.
-
-      * `collect_list` – Required if `windows_events` is included. Contains an array of entries, each of which specifies one Windows Event Log channel to collect. The array must contain at least one entry. Each entry can include the following fields:
-
-        * `event_name` – Required. Specifies the Windows Event Log channel to collect from, such as `System` or `Application`. The maximum length is 255 characters.
-
-        * `event_levels` – Optional. Specifies the event severity levels to collect. Valid values are `CRITICAL`, `ERROR`, `WARNING`, `INFORMATION`, and `VERBOSE`. If you omit this field, the agent collects events of all levels.
-
-        * `event_ids` – Optional. Specifies a list of specific event IDs to collect. Each ID must be between 0 and 65535.
-
-        * `event_format` – Optional. Specifies the output format. Valid values are `xml`, which sends the raw XML of the event, and `text`, which sends a structured representation. If you omit this field, the agent uses `text`.
-
-        * `log_group_name` – Optional. Specifies the log group name to use in CloudWatch Logs. The maximum length is 512 characters. If you omit this field, the agent uses `/aws/cwagent/windows_events`.
-
-        * `log_stream_name` – Optional. Specifies the log stream name to use in CloudWatch Logs. The maximum length is 512 characters. If you omit this field, the agent uses the host identifier and the event channel name, separated by a slash.
-
-    * `host_metrics` – Optional. Specifies that the agent collects host-level system metrics. This section can include the following field:
-
-      * `collection_interval` – Optional. Specifies how often the agent collects the metrics, in seconds. If you omit this field, the agent uses the `metrics_collection_interval` value from the `agent` section, or 30 seconds if that is also omitted.
-
-    * `prometheus` – Optional. Specifies that the agent scrapes metrics from Prometheus targets. This section can include the following field:
-
-      * `config_path` – Required. Specifies the path to the Prometheus scrape configuration file.
-
-
-
-
-Note
-
-Make sure Transaction Search is enabled before you send traces to the OTLP traces endpoint.
-
-The following is an example of an `opentelemetry` section that collects OTLP telemetry and a log file.
-    
-    
-    "opentelemetry": {
-      "collect": {
-        "otlp": {
-          "grpc_endpoint": "0.0.0.0:4317",
-          "http_endpoint": "0.0.0.0:4318",
-          "span_metrics_enabled": true
-        },
-        "files": {
-          "collect_list": [
-            {
-              "file_path": "/var/log/app/*.log",
-              "log_group_name": "/app/{instance_id}",
-              "log_stream_name": "{hostname}",
-              "timestamp_format": "%Y-%m-%d %H:%M:%S",
-              "timezone": "UTC"
-            }
-          ]
-        }
-      }
-    }
-
@@ -1562,6 +1459 @@ This example includes both ways of specifying metrics in the `measurement` secti
-            "force_flush_interval" : 15,
-            "metrics_collected": {
-               "kubernetes": {
-                    "enhanced_container_insights": true
-          }
-        }
+            "force_flush_interval" : 15
@@ -1609,3 +1501,3 @@ The following is an example of a complete CloudWatch agent configuration file fo
-                "customizedCounterName": [
-                  "metric1",
-                  "metric2"
+                "measurement": [
+                  "customizedCounterName1",
+                  "customizedCounterName2"
@@ -1702,4 +1593,0 @@ The following is an example of a complete CloudWatch agent configuration file fo
-## Save the CloudWatch agent configuration file manually
-
-If you create or edit the CloudWatch agent configuration file manually, you can give it any name. After you have created the file, you can copy it to other servers where you want to run the agent.
-