Amazon CloudWatch

Plugin: go.d.plugin Module: cloudwatch

Overview

Monitor AWS infrastructure through Amazon CloudWatch. This collector discovers CloudWatch metrics for a curated set of AWS services and renders them as Netdata charts, with minimal configuration.

Monitored services:

Key terms used throughout this page:

Coverage is defined by profiles – YAML files declaring a CloudWatch namespace, an exact resource-dimension grain, supported regions, metrics, statistics, and chart template. A service can use multiple profiles when AWS publishes distinct grains, and coverage can be extended without collector code changes. See the AWS CloudWatch profile format for the complete schema and authoring rules.

Tip - Need a service that isn’t listed?

Request a profile – it’s just a YAML file, no code change. Open a feature request and attach the service’s CloudWatch metric schema, captured with this read-only command. It prints only metric and dimension names (no resource IDs, ARNs, or metric values), so the output is safe to share:

aws cloudwatch list-metrics --namespace "AWS/<Service>" --region <your-region> --output json \
  | jq -c '[.Metrics[] | {metric: .MetricName, dimensions: ([.Dimensions[].Name] | sort)}] | unique'

Replace AWS/<Service> with the service namespace (for example AWS/AmazonMQ) and <your-region> with a region where the service runs. The exact metrics and dimensions in the output are what we need to author a correct profile quickly.

This collector reads runtime metrics from CloudWatch. It complements the AWS EC2 Compute instances integration (EC2 inventory and capacity) and the AWS Quota integration (AWS Service Quotas). They use different AWS data sources and do not replace one another.

The collector works in three stages:

• Plan – named credential sources, monitored targets, and ordered collection rules are compiled into a fixed runtime plan. Each target resolves its AWS account ID through sts:GetCallerIdentity; target names remain distinct identities even when they resolve to the same account. When selections overlap, rule order – then target order within the rule – decides ownership: the first match owns each exported metric/statistic series.
• Discover – a profile with identifying dimensions finds its resources with one CloudWatch ListMetrics scan per target, region, and namespace, then applies its exact dimension matcher. A profile whose dimensions are all constants is a known static instance and skips ListMetrics. Optional resource-tag filters are resolved with the Resource Groups Tagging API before queries are expanded.
• Query – every selected series gets a resolved timing policy: aggregation period, rolling lookback, and publication delay. GetMetricData searches the aligned rolling window for the newest complete datapoint, and Netdata receives the retained value on every collection cycle.

Built-in collector-activity charts show CloudWatch API calls, calculated billable metric requests, and raw queries, so you can tune the plan and relate collector work to AWS billing.

To start collecting, jump to Setup – every job needs three blocks: credentials (how to authenticate), targets (which AWS identity to monitor), and rules (which services and regions to collect). The sections in between are tuning and cost reference.

This collector is supported on all platforms.

This collector supports collecting metrics from multiple instances of this integration, including remote instances.

The collector also calls sts:GetCallerIdentity for account attribution, but AWS does not require an explicit permission grant for that operation.

Default Behavior

Auto-Detection

The defaults are designed so a minimal configuration collects something useful:

• A rule that omits profiles selects all default-enabled profiles for its targets and regions.
• A rule that omits metrics collects the default-enabled metrics from those profiles.
• A metric group changes only its named profile; other selected profiles keep their defaults. The group keeps the profile’s defaults unless defaults: false; either way, it adds the exact AWS MetricNames it lists.
• Statistics resolve from the metric entry, then the group, then the profile declaration.
• Charts appear only for profiles with live metrics.
• Discovery and the query blueprint are cached; discovery refreshes every discovery.refresh_every seconds (default 300).

Limits

Timing

• The minimum collection interval is 60 seconds (CloudWatch’s minimum metric period).
• Query timing resolves field-by-field: rules[].query, then rule_defaults.query, then metric and profile defaults, then the built-in 10-minute publication delay. The combined publication_delay + lookback + period horizon cannot exceed 14 days.
• The stock S3 storage profile uses a conservative one-day delay policy: AWS documents that S3 storage metrics are reported once per day, without guaranteeing publication within one day.
• A successful sparse query can replay its newest eligible CloudWatch value for up to lookback. During transient AWS failures, the retained value can be replayed longer, until a successful query replaces or expires it.

Plan size

• The collector refuses a plan too large to query safely: more than 20,000 selected series, 600,000 datapoints due in one cycle, or 40 batched GetMetricData requests (up to five statistics for one metric count as a single request). Only very broad rules approach these bounds; narrow regions, profiles, or metrics if you do.
• limits.max_instances (default 1000) bounds distinct final static or discovered instances after tag filtering and overlap resolution. Overflow rejects the refreshed plan; instances are never silently truncated.
• limits.max_discovery_groups (default 64, hard maximum 100) bounds unique (target, region, namespace) discovery groups. Compatible rules and profiles share a group. Larger collection must be split across jobs: one refresh can admit at most 100 groups that reach ListMetrics.

Discovery bounds

• Each discovery group is bounded to 100 ListMetrics pages, 50,000 scanned metrics, 1,000,000 residual profile matches, and 20,000 candidate instances. Overflow fails the group without replacing its previous snapshot.
• One whole discovery refresh is additionally capped at 100 admitted ListMetrics operations, the same scan/match/candidate totals, 64 MiB of candidate storage, and one shared timeout. Every non-skipped group that resolves a client runs its first admitted operation before continuations share the remaining budget.
• Exhausting an aggregate limit or the timeout discards the attempted refresh atomically: the existing snapshot stays active and discovery retries after discovery.refresh_every. On the first pass, all-constant static profiles keep collecting while dynamic discovery waits for its retry; without static work, total discovery failure makes the collection attempt fail.

Labels

• Resources are labeled by their identifying CloudWatch dimensions (for example EC2 instance_id). Selected resource tags can be attached as non-identity labels via labels.resource_tags; changing those tags updates labels without changing chart identity. A dimension that is constant across resources (such as CloudFront’s Region=Global) is matched and queried but not turned into a label.

Performance Impact

What AWS bills

AWS bills CloudWatch API usage. GetMetricData is the cost driver – roughly $0.01 per 1,000 metrics requested (confirm current CloudWatch pricing for your region). ListMetrics discovery falls under the free tier and then costs a fraction as much. Up to five statistics requested for the same metric count as one billable metric request, and the collector’s batching preserves that grouping.

To estimate a job’s normal daily cost:

billable metric requests/day ≈ instances × billable metrics per instance × (86,400 / period seconds)

For example, one Billing series at the stock 10-minute period is 86,400 / 600 = 144 requests per day. For a running job, skip the arithmetic and read the CloudWatch Metric Requests chart described below – it reports the billable metric requests actually submitted.

How the collector keeps cost down

• Each series is queried once per newly eligible period window, not once per Netdata collection cycle.
• Curated profiles, exact metric/statistic/resource-tag selection, and single-statistic defaults keep the selected set small.
• Compatible rules and profiles share discovery scans; discovery and query plans are cached; recently_active_only narrows scans to active resources.
• A transient failure retries after one update_every, then doubles the delay within the same eligible window, capped at the effective period. Retries are billable, so update_every affects failure-time cost even though it does not set the normal query cadence.

Cost scales with selected targets, instances, metrics, statistics beyond AWS’s grouping, periods, and lookback length. Longer lookbacks increase requested datapoints and can disable CloudWatch’s three-hour recently-active discovery filter. To reduce cost, narrow rules[].targets, rules[].profiles, rules[].metrics, rules[].regions, or configure resource tag filters.

Watching collector-issued work

Three collector-activity chart types expose the inputs behind that cost model:

Calls and billable metric requests deliberately have no profile attribution because one shared scan or request can serve multiple profiles; targets that resolve to the same account are aggregated. Each chart reports an absolute count for the interval since the preceding successfully committed collector frame: a cached interval with no real AWS work reports zero, activity from failed cycles carries into the next successful frame, and job replacement or a process restart resets it. The gauges exclude SDK-internal retries and are billing inputs, not an AWS invoice.

Billing profile cost

The opt-in Billing profiles use a 10-minute period, so each selected Billing series normally produces 144 billable metric requests per day before retries (200 series produce 28,800). AWS charges by metrics requested, not by the datapoint slots that the 24-hour lookback reserves. The total profile is static and performs no ListMetrics; the three dynamic Billing grains share one namespace discovery stream per target and refresh interval. Billing cardinality grows with services, linked accounts, and observed account/service pairs, so select only the grains you need.

Setup

You can configure the cloudwatch collector in two ways:

Important

UI configuration requires paid Netdata Cloud plan.

Prerequisites

Create an AWS IAM identity with CloudWatch read access

The collector needs an IAM identity (user or role) allowed to read CloudWatch metrics. It resolves the AWS account identity with sts:GetCallerIdentity, which does not require an explicit permission grant.

Attach a policy such as:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudwatch:ListMetrics",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    }
  ]
}

Permission notes:

• cloudwatch:ListMetrics and cloudwatch:GetMetricData do not support resource-level permissions, so "Resource": "*" is already least-privilege for these read actions.
• A job that selects only profiles whose dimensions are all constants, such as billing_total, can omit cloudwatch:ListMetrics; every dynamic profile needs it.
• sts:GetCallerIdentity needs no explicit grant.
• Scope sts:AssumeRole to the specific role ARN(s) rather than *.
• To enable resource tag filtering or labels, also grant tag:GetResources (it likewise requires "Resource": "*").

In the collector configuration, define one or more named credential sources:

A target can use either source directly or use it to assume one IAM role. If the role trust policy requires an external ID, the role owner supplies that value; it is not an AWS password or access key. See AWS guidance for third-party access.

Enable CloudWatch Billing metrics before selecting Billing profiles

The Billing profiles are opt-in. Before collecting them, enable Receive CloudWatch Billing Alerts in AWS Billing Preferences as described in AWS’s Billing alarm documentation.

This setup action is separate from the collector’s runtime IAM policy:

• Enabling the preference requires the account root user or an IAM principal allowed to view Billing information. The collector identity still needs only the CloudWatch read permissions described above.
• Once enabled, AWS says Billing metric data collection cannot be disabled. Deleting CloudWatch alarms does not disable the metric feed.
• The first data normally appears about 15 minutes after first enablement. AWS then calculates and publishes estimates several times daily, so a working job can legitimately have no chart or can hold the last published value between updates.
• Billing data is published only in us-east-1, represents worldwide charges, and is reported only in USD. The charts show the latest published estimate for the current month, not a forecast.
• For consolidated billing, enable the preference in the management/payer account. That account can expose the consolidated total plus linked-account views; a standalone/member view can contain fewer grains. If the management/payer account changes, enable the preference again in the new account.
• AWS does not publish these Billing metrics for Amazon Partner Network (APN) accounts.

The collector samples and holds the newest successfully retrieved value. Treat the charts as the latest published month-to-date estimate, not an invoice or real-time ledger; chart behavior details are described under Metrics.

Configuration

Options

The following options can be defined globally or per job.

Profile file locations:

A user profile file with the same basename as a stock profile overrides it.

via UI

Configure the cloudwatch collector from the Netdata web interface:

1. Go to Nodes.
2. Select the node where you want the cloudwatch data-collection job to run and click the :gear: (Configure this node). That node will run the data collection.
3. The Collectors → Jobs view opens by default.
4. In the Search box, type cloudwatch (or scroll the list) to locate the cloudwatch collector.
5. Click the + next to the cloudwatch collector to add a new job.
6. Fill in the job fields, then click Test to verify the configuration and Submit to save.
   • Test runs the job with the provided settings and shows whether data can be collected.
   • If it fails, an error message appears with details (for example, connection refused, timeout, or command execution errors), so you can adjust and retest.

via File

The configuration file name for this integration is go.d/cloudwatch.conf.

The file format is YAML. Generally, the structure is:

update_every: 1
autodetection_retry: 0
jobs:
  - name: some_name1
  - name: some_name2

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/cloudwatch.conf

Examples

Default credentials, single region

Monitor the base AWS identity in us-east-1 using the SDK default credential chain and all default-enabled profiles.

jobs:
  - name: default_credentials
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: base
        credentials: sdk_default
    rules:
      - name: base-defaults
        targets: [base]
        regions: [us-east-1]

Static credentials assume multiple roles

Use one static/session credential source to assume roles for multiple monitored targets. Store credentials in supported secret providers, not in plaintext.

jobs:
  - name: cross_account
    credentials:
      - name: bootstrap
        type: static
        type_static:
          access_key_id: ${env:AWS_ACCESS_KEY_ID}
          secret_access_key: ${env:AWS_SECRET_ACCESS_KEY}
          session_token: ${env:AWS_SESSION_TOKEN}
    targets:
      - name: production
        credentials: bootstrap
        assume_role:
          role_arn: "arn:aws:iam::[ACCOUNT]:role/[ROLE]"
          external_id: ${env:AWS_EXTERNAL_ID}
      - name: staging
        credentials: bootstrap
        assume_role:
          role_arn: "arn:aws:iam::[ACCOUNT]:role/[ROLE]"
    rules:
      - name: both-defaults
        targets: [production, staging]
        regions: [us-east-1, eu-west-1]

Add an opt-in metric to a profile

Keep the default EC2 metrics and add CPU credit balance for burstable instances. Because the metric group omits defaults, it defaults to true; omitting statistics inherits the profile-declared Average statistic.

jobs:
  - name: ec2_with_cpu_credits
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: base
        credentials: sdk_default
    rules:
      - name: ec2
        targets: [base]
        profiles:
          defaults: false
          include: [ec2]
        metrics:
          - profile: ec2
            include:
              - name: CPUCreditBalance
        regions: [us-east-1]

Different timing for metrics in one profile

Use disjoint exact metric selections when one service needs different query timing. Earlier rules own only the metric/statistic series they select, so these two Lambda rules do not shadow each other.

jobs:
  - name: lambda_split_policy
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: base
        credentials: sdk_default
    rules:
      - name: lambda-activity
        targets: [base]
        profiles:
          defaults: false
          include: [lambda]
        metrics:
          - profile: lambda
            defaults: false
            statistics: [Sum]
            include:
              - name: Invocations
        regions: [us-east-1]
        query:
          period: 5m
          lookback: 30m
          publication_delay: 10m
      - name: lambda-latency
        targets: [base]
        profiles:
          defaults: false
          include: [lambda]
        metrics:
          - profile: lambda
            defaults: false
            statistics: [Average, p90]
            include:
              - name: Duration
        regions: [us-east-1]
        query:
          period: 1m
          lookback: 5m
          publication_delay: 5m

Lower resolution to reduce cost

Collect the default profiles at five-minute resolution and refresh discovery less often. rule_defaults.query applies field-by-field to every rule that does not override it, replacing profile timing defaults – the daily S3 storage profile is excluded here so the job-wide five-minute policy does not query it before AWS publishes. update_every controls how often charts update and the failure-retry cadence, not the normal query cost.

jobs:
  - name: low_resolution
    update_every: 300
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: base
        credentials: sdk_default
    rule_defaults:
      query:
        period: 5m
        lookback: 15m
    rules:
      - name: five-minute-defaults
        targets: [base]
        profiles:
          exclude: [s3]
        regions: [us-east-1]
    discovery:
      refresh_every: 900

AWS Billing estimated charges

Collect each available exact Billing grain independently. Billing metrics must be enabled first, are published only in us-east-1, and do not support resource-tag filters or resource-tag-derived labels. The stock profiles use a 10-minute period and 24-hour retrieval window; a rules[].query block would override only the fields it sets.

jobs:
  - name: billing_estimated_charges
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: billing
        credentials: sdk_default
    rules:
      - name: billing-grains
        targets: [billing]
        profiles:
          defaults: false
          include:
            - billing_total
            - billing_service
            - billing_linked_account
            - billing_linked_account_service
        regions: [us-east-1]
        filters:
          # Billing is not an RGTA resource. This explicitly
          # disables any inherited resource-tag filter.
          resource_tags: []

AWS PrivateLink endpoints with split timing

Collect endpoint-level Average statistics every minute, independently collect six-hour processed-byte Sum windows normalized to bytes/s, and opt into the higher-cardinality endpoint-by-subnet view. Both endpoint grains support the same VPC endpoint resource-tag filters and labels; subnet charts inherit their parent endpoint’s tags.

jobs:
  - name: privatelink_endpoints
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: base
        credentials: sdk_default
    rule_defaults:
      filters:
        resource_tags:
          - key: environment
            values: [production]
    rules:
      - name: endpoint-averages
        targets: [base]
        profiles:
          defaults: false
          include: [privatelink_endpoint]
        metrics:
          - profile: privatelink_endpoint
            defaults: false
            statistics: [Average]
            include:
              - name: ActiveConnections
              - name: BytesProcessed
              - name: NewConnections
        regions: [us-east-1]
        query:
          period: 1m
          lookback: 5m
          publication_delay: 5m
      - name: endpoint-six-hour-bytes
        targets: [base]
        profiles:
          defaults: false
          include: [privatelink_endpoint]
        metrics:
          - profile: privatelink_endpoint
            defaults: false
            include:
              - name: BytesProcessed
                statistics: [Sum]
        regions: [us-east-1]
        query:
          period: 6h
          lookback: 6h
          publication_delay: 5m
      - name: endpoint-subnets
        targets: [base]
        profiles:
          defaults: false
          include: [privatelink_endpoint_subnet]
        regions: [us-east-1]
    labels:
      resource_tags:
        - key: Name

AWS PrivateLink services with split timing

Collect provider-side traffic averages every minute, connected-endpoint count every five minutes, and independently collect six-hour processed-byte Sum windows normalized to bytes/s. Every grain joins tags through its parent VPC endpoint service, including the service-by-consumer-endpoint view.

jobs:
  - name: privatelink_services
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: base
        credentials: sdk_default
    rule_defaults:
      filters:
        resource_tags:
          - key: environment
            values: [production]
    rules:
      - name: service-traffic-averages
        targets: [base]
        profiles:
          defaults: false
          include: [privatelink_service]
        metrics:
          - profile: privatelink_service
            defaults: false
            statistics: [Average]
            include:
              - name: ActiveConnections
              - name: BytesProcessed
              - name: NewConnections
              - name: RstPacketsSent
        regions: [us-east-1]
        query:
          period: 1m
          lookback: 5m
          publication_delay: 5m
      - name: service-endpoint-count
        targets: [base]
        profiles:
          defaults: false
          include: [privatelink_service]
        metrics:
          - profile: privatelink_service
            defaults: false
            include:
              - name: EndpointsCount
                statistics: [Average]
        regions: [us-east-1]
        query:
          period: 5m
          lookback: 5m
          publication_delay: 5m
      - name: service-six-hour-bytes
        targets: [base]
        profiles:
          defaults: false
          include: [privatelink_service]
        metrics:
          - profile: privatelink_service
            defaults: false
            include:
              - name: BytesProcessed
                statistics: [Sum]
        regions: [us-east-1]
        query:
          period: 6h
          lookback: 6h
          publication_delay: 5m
    labels:
      resource_tags:
        - key: Name

All services including opt-in profiles

Select defaults and explicitly add every disabled opt-in profile, including detailed PrivateLink endpoint/service grains and four Billing grains. Their cardinality, prerequisites, and cost guidance still apply.

jobs:
  - name: defaults_and_opt_in
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: base
        credentials: sdk_default
    rules:
      - name: expanded-services
        targets: [base]
        profiles:
          defaults: true
          include:
            - alb_target
            - dynamodb_operation
            - s3_requests
            - ebs_stalled_io
            - privatelink_endpoint_subnet
            - privatelink_service_az
            - privatelink_service_load_balancer
            - privatelink_service_az_load_balancer
            - privatelink_service_vpc_endpoint
            - billing_total
            - billing_service
            - billing_linked_account
            - billing_linked_account_service
        regions: [us-east-1]

Filter resources by tag and add tag labels

Apply one job-wide exact tag filter, disable it for an unsupported profile, and expose selected AWS tags as mutable non-identity chart labels.

jobs:
  - name: tagged_resources
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: base
        credentials: sdk_default
    rule_defaults:
      filters:
        resource_tags:
          - key: managed-by
            values: [platform]
    rules:
      - name: filtered-defaults
        targets: [base]
        regions: [us-east-1]
      - name: unfiltered-cloudfront
        targets: [base]
        profiles:
          defaults: false
          include: [cloudfront]
        regions: [us-east-1]
        filters:
          resource_tags: []
    labels:
      resource_tags:
        - key: Name
        - key: owner
          label: resource_owner
    limits:
      max_instances: 1000
      max_discovery_groups: 64

Present AWS metrics on a virtual node

Attach the job to a virtual node so CloudWatch metrics appear as their own Netdata node instead of on the node running the collector. The virtual node must already be defined in the Agent’s vnodes configuration.

jobs:
  - name: aws_production
    vnode: aws-production
    credentials:
      - name: sdk_default
        type: default
    targets:
      - name: base
        credentials: sdk_default
    rules:
      - name: base-defaults
        targets: [base]
        regions: [us-east-1]

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Charts are generated at runtime from the active service profiles:

• Each static or discovered AWS instance becomes a chart instance identified by its account_id, region, and the profile’s identifying dimensions (for example instance_id for EC2, or bucket_name and storage_type for S3).
• All contexts live under the cloudwatch. namespace.
• Metrics land on the job’s configured vnode when present, otherwise on the node running the collector. Individual AWS resources are distinguished by labels, not created as separate Netdata nodes.
• CloudWatch publishes with a delay, so allow a few minutes for the first datapoints.

Every job also emits three collector-activity chart types in the same cloudwatch.* namespace: cloudwatch.collector_api_calls (labeled operation instances, calls dimension), cloudwatch.collector_metric_requests (requests dimension), and cloudwatch.collector_queries (labeled profile instances, queries dimension). They report absolute counts for the interval since the preceding successfully committed collector frame; they measure collector-issued work, not an AWS invoice.

The built-in profiles ship the following charts by default. Each service links to its profile – the authoritative definition of its exact metrics, statistics, dimensions, and charts:

Stock profiles can also declare opt-in metrics (disabled: true on the metric). They are not queried or billed by default, and their chart definitions are already part of the profile:

• Enable one through that profile’s rules[].metrics[].include; the chart materializes once the selected series emits data.
• The metric group keeps the profile’s default-enabled metrics unless defaults: false, and omitted statistics inherit the profile declaration.
• There is no need to copy and edit a stock profile merely to enable a curated metric.

Stock profiles are shipped at /usr/lib/netdata/conf.d/go.d/cloudwatch.profiles/default/; custom profile overrides live under /etc/netdata/go.d/cloudwatch.profiles/ and require a go.d restart because the catalog is cached process-wide.

These disabled opt-in profiles are collected when a rule names them in profiles.include:

Billing grains. The Billing profiles are exact grains rather than one wildcard: select only the views you need. All use EstimatedCharges, statistic Maximum, USD, a 10-minute period, and a 24-hour retrieval window.

• AWS publishes the underlying estimate several times daily; the collector re-emits the newest successful value between publications.
• Around the UTC month boundary, a prior-month value can remain visible until a successful query replaces or expires it, and transient AWS failures can retain it longer.
• region=us-east-1 identifies the CloudWatch publication/query location; the charge itself is worldwide.
• Billing dimensions are not Resource Groups Tagging API resources, so resource-tag filters and tag-derived labels do not apply.
• A valid job can produce no Billing chart when AWS has not published the selected grain.

PrivateLink endpoint grains. The default privatelink_endpoint profile identifies one endpoint by endpoint_type, service_name, vpc_endpoint_id, and vpc_id. The opt-in privatelink_endpoint_subnet profile adds subnet_id; enable it deliberately, because every endpoint can produce several subnet chart instances and seven additional metric/statistic queries per instance. Both profiles share one AWS/PrivateLinkEndpoints discovery scan and one VPC endpoint tag association, so endpoint resource-tag filters and labels also apply to every subnet child. The stock surface exports Average and per-second Sum views where both are useful; exact metric/statistic rules can assign different timing without shadowing siblings.

PrivateLink service grains. The default privatelink_service profile identifies the provider service by service_id and is the only grain that exports EndpointsCount. The opt-in profiles split by availability_zone, load_balancer_arn, both, or consumer vpc_endpoint_id. All five share one AWS/PrivateLinkServices discovery scan and join tags through the parent endpoint service (ec2:vpc-endpoint-service). The collector deliberately does not attach endpoint or load-balancer tags to detailed children – a vpc_endpoint_id can identify a consumer endpoint outside the service-owning account. EndpointsCount is read on its documented five-minute cadence and records zero when no datapoint is published; traffic gauges show gaps when absent.

PrivateLink cost. At stock timing (five-minute period, lookback, and publication delay), an endpoint, subnet, or default service instance has five structural CloudWatch metrics: (86,400 / 300) × 5 = 1,440 billable metric requests per day before retries. Each opt-in detailed service instance has four, or 1,152 per day. A one-minute override runs its selected metrics five times as often; narrow profiles, metrics, regions, grains, and resource tags when that freshness is not required.

Cardinality warning. These opt-in profiles include potentially high-cardinality data. S3 Request Metrics additionally require per-bucket request-metrics configuration in AWS and are billed at CloudWatch custom-metric rates; they collect nothing until enabled on the bucket. PrivateLink cardinality grows with endpoint subnets, service Availability Zones, load balancers, and consumer endpoints; the combined Availability Zone/load-balancer grain multiplies those dimensions. The Billing service/account grains grow with the payer’s services and linked accounts.

Per AWS account, region, and operation

Collector-issued CloudWatch API work attributed to one resolved AWS account, region, and API operation.

Labels:

Metrics:

Per AWS account and region

Calculated billable CloudWatch metric requests attributed to one resolved AWS account and region.

Labels:

Metrics:

Per AWS account, region, and profile

Raw CloudWatch metric-data queries attributed to their source profile for collection-plan tuning.

Labels:

Metrics:

Alerts

The following alerts are available:

Troubleshooting

Debug Mode

Important: Debug mode is not supported for data collection jobs created via the UI using the Dyncfg feature.

To troubleshoot issues with the cloudwatch collector, run the go.d.plugin with the debug option enabled. The output should give you clues as to why the collector isn’t working.

• Navigate to the plugins.d directory, usually at /usr/libexec/netdata/plugins.d/. If that’s not the case on your system, open netdata.conf and look for the plugins setting under [directories].

  cd /usr/libexec/netdata/plugins.d/
  

• Switch to the netdata user.

  sudo -u netdata -s
  

• Run the go.d.plugin to debug the collector:

  ./go.d.plugin -d -m cloudwatch
  

  To debug a specific job:

  ./go.d.plugin -d -m cloudwatch -j jobName
  

Getting Logs

If you’re encountering problems with the cloudwatch collector, follow these steps to retrieve logs and identify potential issues:

• Run the command specific to your system (systemd, non-systemd, or Docker container).
• Examine the output for any warnings or error messages that might indicate issues. These messages should provide clues about the root cause of the problem.

System with systemd

Use the following command to view logs generated since the last Netdata service restart:

journalctl _SYSTEMD_INVOCATION_ID="$(systemctl show --value --property=InvocationID netdata)" --namespace=netdata --grep cloudwatch

System without systemd

Locate the collector log file, typically at /var/log/netdata/collector.log, and use grep to filter for collector’s name:

grep cloudwatch /var/log/netdata/collector.log

Note: This method shows logs from all restarts. Focus on the latest entries for troubleshooting current issues.

Docker Container

If your Netdata runs in a Docker container named “netdata” (replace if different), use this command:

docker logs netdata 2>&1 | grep cloudwatch

No metrics are collected

Check the following:

• Permissions – every target allows cloudwatch:GetMetricData; targets selecting any profile with dynamic dimensions also require cloudwatch:ListMetrics. All-constant profiles such as billing_total skip discovery and do not need ListMetrics. sts:GetCallerIdentity needs no explicit grant. Targets with assume_role also require sts:AssumeRole on the source identity. Resource tag filtering or labels require tag:GetResources.
• Rules – rules[].targets, rules[].profiles, optional rules[].metrics, and rules[].regions select the expected target, service, exact metric/statistic, and region. CloudFront publishes metrics only in us-east-1; its profile enforces this automatically.
• Resource filters – a rule that omits filters.resource_tags inherits rule_defaults.filters.resource_tags. An explicitly included profile without a safe Resource Groups Tagging API association is rejected; use filters.resource_tags: [] for a deliberate unfiltered rule.
• Resources are active – confirm in the AWS CloudWatch console that the resources are publishing metrics.
• Timeout – discovery shares one timeout (default 30 seconds) across a whole refresh. A large scope can exhaust it; the refresh is then discarded and retried after discovery.refresh_every. Raise timeout or narrow the scope.
• Collector logs – check for authentication or API errors:

  # systemd
  journalctl -u netdata --namespace=netdata --grep cloudwatch --since "5 minutes ago"
  # non-systemd
  grep cloudwatch /var/log/netdata/collector.log
  

Missing metrics for some services

• Profile selection – omit rules[].profiles to select defaults, or ensure the service basename appears under rules[].profiles.include and is not excluded.
• Metric selection – omit rules[].metrics to collect default-enabled metrics. A group changes only its named profile and keeps those defaults unless defaults: false; every include[].name must be an exact AWS MetricName. Statistics may come from the metric entry, group, or profile declaration.
• Daily metrics – AWS documents that S3 storage metrics are reported once per day, but does not state a publication-within-one-day guarantee. The stock profile therefore uses a conservative 1d collector delay policy, and recently_active_only is automatically disabled for its long query horizon.
• Resource activity – some metrics only appear when the resource is actively processing data (for example, EventBridge and Bedrock publish a metric only when its value is non-zero).
• Auto Scaling group metrics – Auto Scaling group metrics (cloudwatch.auto_scaling.*) are not published until group-metrics collection is enabled on the group (aws autoscaling enable-metrics-collection --granularity 1Minute). Amazon EKS managed node groups have it enabled by default.
• EKS control-plane metrics – EKS control-plane metrics (cloudwatch.eks.*) are published to the AWS/EKS namespace automatically, at no additional EKS charge, only for clusters running Kubernetes 1.28 or later; older clusters do not report them. These are distinct from Container Insights / the CloudWatch Observability add-on (agent-based, billed separately).

Charts have gaps or incomplete data

CloudWatch publishes metrics with a delay.

• Keep rules[].query.period at or above the metric’s real publication cadence. A shorter override increases billed query frequency but cannot make AWS publish more often, so it can create empty windows.
• Set rules[].query.publication_delay when a workload publishes completed buckets later than its profile or the built-in 10m fallback.
• Check rule_defaults.query.publication_delay before overriding an individual rule. A job-wide value replaces profile-specific delays for inheriting rules, including the stock S3 storage profile’s conservative 1d, and a shorter value can query daily data before it is published.
• Set rules[].query.lookback to search a wider rolling window for sparse datapoints. It must be an exact multiple of the effective period.
• Stale-looking values – a successful query presents its newest eligible datapoint on every Netdata collection cycle, so an old CloudWatch value can appear current for up to lookback. During transient AWS failures, replay can continue longer until a successful query replaces or expires it.
• Longer lookbacks increase response work and may disable recently_active_only for the shared discovery scan.
• Transient query failures preserve the retained value and retry after one update_every; later delays double within the same eligible window up to the effective period. A newly eligible window resets the backoff.

Discovery group limit exceeded

A discovery group is one unique (target, region, namespace) combination. Compatible rules and profiles share the same group. limits.max_discovery_groups defaults to 64 to bound accidental ListMetrics expansion.

This can result from accidental target/region/profile expansion or from a legitimate large installation. Verify the derived scope first. For intentional scale, raise the safeguard up to 100. Beyond 100, split the configuration across multiple jobs: one bounded refresh admits at most 100 ListMetrics SDK operations, and every non-skipped group that resolves a client reaches its first admitted operation before continuations. Skipped groups and client-resolution failures consume no operation budget. Splitting preserves metric coverage while keeping each job’s discovery cost, memory, and completion time bounded.

Job fails to start or the plan is rejected

Configuration validation and plan preflight fail loudly instead of silently truncating; the collector log names the exact bound or reference that failed.

• Names and references – credential, target, and rule names must be lowercase, start with a letter, use only letters, digits, _, and -, and stay within 64 characters. Every target and rule reference must point to a defined name.
• Partition mismatch – all regions selected for one target must belong to one AWS partition, and an assumed-role ARN must match it. Split partitions across targets or jobs.
• Plan size – more than 20,000 selected series, 600,000 datapoints due in one cycle, or 40 batched GetMetricData requests rejects the plan. Narrow rules or split the configuration across jobs.
• limits.max_instances – more distinct final instances than the limit (default 1000) rejects the refreshed plan. Raise the limit deliberately or narrow the selection; instances are never silently truncated.

Access denied or authentication errors

• Verify the credential source referenced by the failing target is valid and not expired.
• For a target with assume_role, confirm its source identity is allowed to assume the role and that the role trust policy permits it. If the trust policy requires an external ID, use the value supplied by the role owner.
• For AWS GovCloud or China partitions, ensure each target’s selected rule regions match its role ARN partition.