Awscloudwatch Receiver

Available in: contrib Maintainers: @schmikei, @dyl10s Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Getting Started

This receiver uses the AWS SDK as mode of authentication, which includes Credentials File and IMDS 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.
`metrics`	optional	`Metrics`	Configuration for metrics collection via GetMetricData. See Metrics Parameters.
`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 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 below.

Auto-discovery (`discovery`)

Instead of listing metrics manually, the receiver can call ListMetrics 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 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:

Metric name: amazonaws.com/{Namespace}/{MetricName} (CloudWatch casing preserved)
Resource attributes: cloud.provider = aws, cloud.region = <configured 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):

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):

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):

awscloudwatch:
  region: us-east-1
  metrics:
    collection_interval: 5m
    period: 300s
    delay: 10m
    discovery:
      filters:
        namespace: AWS/EC2
      limit: 200

Logs Autodiscovery Example Configuration

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

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

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.

Default
- Minimal configuration of the receiver
- Performs autodiscovery
- Collects all log groups and log streams
Autodiscover Filtering Log Groups
- Performs autodiscovery
- Only collects log groups matching a prefix
- Limits the number of discovered Log Groups
Autodiscover Filtering Log Streams
- Performs autodiscovery for all Log Groups
- Filters log streams
Named Groups
- Specifies and only collects from the desired Log Groups
- Does not attempt autodiscovery
Named Groups Filter Log Streams
- Specifies the names of the log groups to collect
- Does not attempt autodiscovery
- Only collects from log streams matching a prefix

Configuration

Example Configuration

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-08-24

​Awscloudwatch Receiver

​Supported Telemetry

​Overview

​Getting Started

​Configuration

​Top Level Parameters

​Logs Parameters

​Group Parameters

​Metrics collection

​Scraper settings

​Explicit queries (queries)

​Auto-discovery (discovery)

​Statistics

​Output format

​Examples

​Logs Autodiscovery Example Configuration

​Logs Autodiscovery with Account ID Filtering Example

​Logs Named Groups Example

​Sample Configs

​Configuration

​Example Configuration

Awscloudwatch Receiver

Supported Telemetry

Overview

Getting Started

Configuration

Top Level Parameters

Logs Parameters

Group Parameters

Metrics collection

Scraper settings

Explicit queries (`queries`)

Auto-discovery (`discovery`)

Statistics

Output format

Examples

Logs Autodiscovery Example Configuration

Logs Autodiscovery with Account ID Filtering Example

Logs Named Groups Example

Sample Configs

Configuration

Example Configuration