> ## Documentation Index > Fetch the complete documentation index at: https://otel.fyi/llms.txt > Use this file to discover all available pages before exploring further. # Awscloudwatch > OpenTelemetry receiver for Awscloudwatch # Awscloudwatch Receiver ![Status](https://img.shields.io/badge/status-alpha-red) **Available in:** `contrib` **Maintainers:** [@schmikei](https://github.com/schmikei), [@dyl10s](https://github.com/dyl10s) **Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver) ## Supported Telemetry ![Logs](https://img.shields.io/badge/logs-alpha-blue) ![Metrics](https://img.shields.io/badge/metrics-alpha-green) ## Overview ## Getting Started This receiver uses the [AWS SDK](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html) as mode of authentication, which includes [Credentials File](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) and [IMDS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) authentication for EC2 instances. ## Configuration ### Top Level Parameters | Parameter | Notes | type | Description | | --------------- | ---------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `region` | *required* | string | The AWS recognized region string | | `profile` | *optional* | string | The AWS profile used to authenticate, if none is specified the default is chosen from the list of profiles | | `imds_endpoint` | *optional* | string | A way of specifying a custom URL to be used by the EC2 IMDS client to validate the session. If unset, and the environment variable `AWS_EC2_METADATA_SERVICE_ENDPOINT` has a value the client will use the value of the environment variable as the endpoint for operation calls. | | `logs` | *optional* | `Logs` | Configuration for logs collection. See [Logs Parameters](#logs-parameters). | | `metrics` | *optional* | `Metrics` | Configuration for metrics collection via GetMetricData. See [Metrics Parameters](#metrics-parameters-getmetricdata--listmetrics). | | `storage` | *optional* | string | The ID of a storage extension to be used for state persistence. | ### Logs Parameters | Parameter | Type | Default | Description | | ------------------------ | -------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `start_from` | String | Read all available logs from the beginning | Timestamp in `RFC3339` format (e.g., 2006-01-02T15:04:05Z07:00) indicating where to start reading logs. Mutually exclusive with `initial_lookback`. | | `initial_lookback` | Duration | 0 | How far back from the collector's startup time to begin collecting logs (e.g., `1h`). Mutually exclusive with `start_from`. | | `poll_interval` | Duration | 1 minute | Time to wait between log requests | | `max_events_per_request` | Integer | 1,000 | The maximum number of events to process per request to Cloudwatch | | `groups` | Optional | All Log Groups and Streams | Configuration for Log Groups, by default all Log Groups and Log Streams will be collected. | ### Group Parameters `autodiscover` and `named` are ways to control and filter which log groups and log streams which are collected from. They are mutually exclusive and are incompatible to be configured at the same time. * `autodiscover` * `limit`: (optional; default = 50) Limits the number of discovered log groups. This does not limit how large each API call to discover the log groups will be. * `prefix`: (optional) A prefix for log groups to limit the number of log groups discovered. * Only one of `prefix` or `pattern` can be specified. If both are omitted, all log streams up to the limit are collected. * `pattern`: (optional) A case-sensitive substring (not a regular expression) that must be present in the log group names, used to limit the number of log groups discovered. * Only one of `prefix` or `pattern` can be specified. If both are omitted, all log streams up to the limit are collected. * `account_identifiers`: (optional) A list of AWS account IDs to filter log groups by. Only log groups from the specified accounts will be discovered. * `include_linked_accounts`: (optional; default = false) When using a monitoring account, set this to `true` to have autodiscovery return log groups in the accounts listed in `account_identifiers`. If this is `true` and `account_identifiers` contains a `null` value, all log groups in the monitoring account and in all linked source accounts are returned (behavior is handled by the AWS CloudWatch Logs API). * `streams`: (optional) If `streams` is omitted, then all streams will be attempted to retrieve events from. * `names`: A list of full log stream names to filter the discovered log groups to collect from. * `prefixes`: A list of prefixes to filter the discovered log groups to collect from. * `named` * This is a map of log group name to stream filtering options * `streams`: (optional) * `names`: A list of full log stream names to filter the discovered log groups to collect from. * `prefixes`: A list of prefixes to filter the discovered log groups to collect from. ### Metrics collection Metrics are scraped on a configurable interval using the CloudWatch [GetMetricData](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricData.html) API. You can either list the metrics you want explicitly under `queries`, or let the receiver discover them automatically via `discovery`. The two options are mutually exclusive. #### Scraper settings | Parameter | Type | Default | Description | | --------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `collection_interval` | Duration | 5 minutes | How often to poll CloudWatch for new data points. | | `period` | Duration | 5 minutes | The CloudWatch aggregation window. Must match the resolution of the metrics you are collecting. | | `delay` | Duration | 10 minutes | How far back from now the query window ends. CloudWatch metrics are typically available within 3–10 minutes of being recorded; increase this value if you observe missing data points. Each scrape covers exactly one `collection_interval` worth of data ending at `now - delay`, so consecutive scrapes never overlap. | #### Explicit queries (`queries`) List every metric you want to collect. Each entry supports: | Parameter | Type | Required | Description | | ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `namespace` | String | yes | CloudWatch namespace, e.g. `AWS/EC2`. | | `metric_name` | String | yes | CloudWatch metric name, e.g. `CPUUtilization`. | | `dimensions` | Map | no | CloudWatch dimension key/value pairs. Required for metrics that are scoped to a specific resource (e.g. a single EC2 instance or DynamoDB table). Original casing is preserved. | | `stats` | List of strings | no | Which CloudWatch statistics to fetch. See [Statistics](#statistics) below. | #### Auto-discovery (`discovery`) Instead of listing metrics manually, the receiver can call [ListMetrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_ListMetrics.html) to discover them automatically. | Parameter | Type | Default | Description | | --------------------- | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | `filters` | Object | — | Optional sub-block to narrow which metrics are discovered. If omitted, all metrics in all namespaces are discovered. | | `filters.namespace` | String | — | Restrict discovery to a single namespace (e.g. `AWS/EC2`). | | `filters.metric_name` | String | — | Restrict discovery to metrics with this name. | | `limit` | Integer | 100 | Maximum number of metrics to discover and scrape per collection cycle. | | `stats` | List of strings | — | Statistics to fetch for every discovered metric. Same values as in `queries`. | #### Statistics The `stats` field controls which CloudWatch statistics are fetched and how they are represented in OpenTelemetry: * **Omitted (default):** the four standard statistics — `Sum`, `SampleCount`, `Minimum`, `Maximum` — are fetched and combined into a single **Summary** data point per timestamp (`sum`, `count`, quantile 0.0 for minimum, quantile 1.0 for maximum). This matches the [CloudWatch Metric Streams OpenTelemetry 1.0.0 format](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-metric-streams-formats-opentelemetry-100.html) and costs 4 API sub-queries per metric per scrape. * **Explicit list:** only the listed statistics are fetched, each costing one API sub-query. Each produces a separate **Gauge** data point on the same metric, identified by a `stat` attribute (e.g. `stat = Average`). Use this when you only need a subset of statistics to reduce AWS API costs. Different metrics in the same `queries` list can have different `stats`. Standard statistics: `Average`, `Sum`, `Minimum`, `Maximum`, `SampleCount`. Extended statistics (percentiles, trimmed means, etc.): `p99`, `p95`, `p50`, `tm99`, `wm99`, etc. Extended statistics are only supported on metrics that explicitly enable them in CloudWatch — requesting an unsupported extended statistic returns no data. #### Output format All metrics follow the [CloudWatch Metric Streams OpenTelemetry 1.0.0 format](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-metric-streams-formats-opentelemetry-100.html): * **Metric name:** `amazonaws.com/{Namespace}/{MetricName}` (CloudWatch casing preserved) * **Resource attributes:** `cloud.provider = aws`, `cloud.region = ` * **Data point attributes:** `Namespace`, `MetricName`, and `Dimensions` (a nested key/value map, omitted when no dimensions are set) #### Examples Collect two EC2 metrics as Summary (all four standard statistics): ```yaml theme={null} awscloudwatch: region: us-east-1 metrics: collection_interval: 1m period: 60s queries: - namespace: AWS/EC2 metric_name: CPUUtilization dimensions: InstanceId: i-1234567890abcdef0 - namespace: AWS/EC2 metric_name: NetworkIn ``` Collect specific statistics only (Gauge output, fewer API sub-queries per metric): ```yaml theme={null} awscloudwatch: region: us-east-1 metrics: collection_interval: 1m period: 60s queries: - namespace: AWS/EC2 metric_name: CPUUtilization stats: - Average - p99 - namespace: AWS/DynamoDB metric_name: SuccessfulRequestLatency dimensions: TableName: my-table Operation: GetItem stats: - p50 - p95 - p99 ``` Auto-discover all EC2 metrics (Summary output): ```yaml theme={null} awscloudwatch: region: us-east-1 metrics: collection_interval: 5m period: 300s delay: 10m discovery: filters: namespace: AWS/EC2 limit: 200 ``` #### Logs Autodiscovery Example Configuration ```yaml theme={null} awscloudwatch: region: us-west-1 logs: poll_interval: 1m groups: autodiscover: limit: 100 prefix: /aws/eks/ streams: prefixes: [kube-api-controller] ``` #### Logs Autodiscovery with Account ID Filtering Example ```yaml theme={null} awscloudwatch: region: us-west-1 logs: poll_interval: 1m groups: autodiscover: limit: 100 account_identifiers: ["123456789012", "987654321098"] include_linked_accounts: true prefix: /aws/lambda/ ``` #### Logs Named Groups Example ```yaml theme={null} awscloudwatch: region: us-west-1 logs: poll_interval: 5m groups: named: /aws/eks/dev-0/cluster: names: [kube-apiserver-ea9c831555adca1815ae04b87661klasdj] ``` ## Sample Configs This receiver has a number of sample configs for reference. 1. [Default](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver/testdata/sample-configs/default.yaml) * Minimal configuration of the receiver * Performs autodiscovery * Collects all log groups and log streams 2. [Autodiscover Filtering Log Groups](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver/testdata/sample-configs/autodiscover-filter-groups.yaml) * Performs autodiscovery * Only collects log groups matching a prefix * Limits the number of discovered Log Groups 3. [Autodiscover Filtering Log Streams](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver/testdata/sample-configs/autodiscover-filter-streams.yaml) * Performs autodiscovery for all Log Groups * Filters log streams 4. [Named Groups](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver/testdata/sample-configs/named-prefix.yaml) * Specifies and only collects from the desired Log Groups * Does not attempt autodiscovery 5. [Named Groups Filter Log Streams](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awscloudwatchreceiver/testdata/sample-configs/named-prefix-streams.yaml) * Specifies the names of the log groups to collect * Does not attempt autodiscovery * Only collects from log streams matching a prefix ## Configuration ### Example Configuration ```yaml theme={null} aws_cloudwatch/default: region: us-west-1 logs: poll_interval: 1m aws_cloudwatch/initial-lookback: region: us-west-1 logs: poll_interval: 1m initial_lookback: 1h aws_cloudwatch/prefix-log-group-autodiscover: region: us-west-1 logs: poll_interval: 1m groups: autodiscover: limit: 100 prefix: /aws/eks/ aws_cloudwatch/name-pattern-log-group-autodiscover: region: us-west-1 logs: poll_interval: 1m groups: autodiscover: limit: 100 pattern: eks aws_cloudwatch/autodiscover-filter-streams: region: us-west-1 logs: poll_interval: 1m groups: autodiscover: limit: 100 streams: prefixes: [kube-api-controller] aws_cloudwatch/named-prefix-with-streams: profile: "my-profile" region: us-west-1 logs: poll_interval: 5m groups: named: /aws/eks/dev-0/cluster: names: [kube-apiserver-ea9c831555adca1815ae04b87661klasdj] aws_cloudwatch/named-prefix: profile: "my-profile" region: us-west-1 logs: poll_interval: 5m groups: named: /aws/eks/dev-0/cluster: aws_cloudwatch/metrics-explicit: region: us-east-1 metrics: collection_interval: 1m period: 60s queries: - namespace: AWS/EC2 metric_name: CPUUtilization dimensions: InstanceId: i-1234567890abcdef0 - namespace: AWS/EC2 metric_name: NetworkIn aws_cloudwatch/metrics-explicit-gauge: region: us-east-1 metrics: collection_interval: 1m period: 60s queries: - namespace: AWS/EC2 metric_name: CPUUtilization stats: [Average, p99] aws_cloudwatch/metrics-discovery: region: us-east-1 metrics: collection_interval: 5m period: 300s discovery: filters: namespace: AWS/EC2 limit: 200 aws_cloudwatch/metrics-discovery-gauge: region: us-east-1 metrics: collection_interval: 5m period: 300s discovery: filters: namespace: AWS/EC2 limit: 100 stats: [Sum, Average] aws_cloudwatch/metrics-discovery-no-namespace: region: us-west-2 metrics: collection_interval: 2m period: 120s discovery: limit: 50 ``` *** *Last generated: 2026-07-06*