amazon-cloudwatch-agent: host metrics, logs and traces for AWS

One agent across EC2 and the hybrid estate

The repository describes the Amazon CloudWatch Agent as software that enables you to collect and export host-level metrics and logs on instances running Linux or Windows server.

The five things the overview says the agent does are worth reading one at a time, because the third and fourth are where it differs from what EC2 already gives you.

First, it collects more system-level metrics from Amazon EC2 instances across operating systems. The metrics can include in-guest metrics, in addition to the metrics for EC2 instances, and the additional metrics are listed in the documentation page for Metrics Collected by the CloudWatch Agent. Second, it collects system-level metrics from on-premises servers, which can include servers in a hybrid environment as well as servers not managed by AWS at all.

Third, it retrieves custom metrics from your applications or services using the StatsD and collectd protocols, with StatsD supported on both Linux servers and servers running Windows Server and collectd supported only on Linux servers. Fourth, it collects logs from Amazon EC2 instances and on-premises servers, running either Linux or Windows Server. Fifth, it collects Open Telemetry and AWS X-Ray traces.

So the agent covers three different telemetry shapes: what the operating system reports, what your application reports over a metrics protocol, and what your code emits as logs or traces. The in-guest distinction in the first point is the one to internalise, because EC2 instance metrics are free and produced by the hypervisor, while in-guest metrics are produced by the agent and are billed as custom metrics.

The primary language is Go, the licence is MIT, and the default branch is main. The recent releases are v1.300073.0 from 2026-09-30, v1.300072.0 from 2026-09-18 and v1.300071.0 from 2026-08-19, with the last push on 2026-10-20.

An OpenTelemetry collector with telegraf inside it

The architecture is stated in one sentence and it explains most of the repository's layout. Amazon CloudWatch Agent uses open-source projects telegraf and opentelemetry-collector as its dependencies. It operates by starting an opentelemetry collector and is capable of operating pipelines consisting of both telegraf and opentelemetry components in addition to customized components.

So the agent is not a bespoke daemon that happens to scrape things. It is an OpenTelemetry Collector with telegraf's plugins available inside the same process, and the pipeline is assembled from receivers, processors and exporters. That is why the repository has directories named receiver, processor, translator, exporter-style components and plugins, and why the go.mod file is mostly about which versions of the collector and of telegraf to compile against.

The practical consequence is that the configuration file is not a bespoke format. The log filtering example in the README is a JSON document with a collect_list, which is the telegraf plugin configuration shape, and the agent adds the CloudWatch-specific pieces around it.

The Makefile shows the same story from the build side. There are per-platform build variables for Linux amd64, Linux arm64, Windows amd64, and Darwin on both amd64 and arm64, and the Linux and Windows builds set CGO_ENABLED=0 while the Darwin builds set CGO_ENABLED=1. The version and build timestamp are stamped into the binary at link time through the cfg/agentinfo package, and the default build mode is PIE.

Application metrics arrive over StatsD and collectd

The application metrics path is the part that turns the agent from a system collector into a general telemetry agent.

StatsD is supported on both Linux servers and servers running Windows Server. collectd is supported only on Linux servers. That asymmetry is worth knowing before you plan a hybrid estate, because a Windows application that emits metrics has to do it over StatsD, and anything that only speaks the collectd protocol has to be on Linux.

The reason for supporting two protocols is that they cover different existing estates. StatsD is the convention in the application and games world, where a library pushes counters and timers over UDP to a port. collectd is the convention in server and systems monitoring, where a plugin pushes values to a socket. Supporting both means an agent can be dropped onto hosts whose applications already export in one of those formats, without asking the applications to change.

The trade-off is that both protocols are push-based and lossy by design, and they carry no metadata about the host. The agent provides the host context, the application provides the metric, and the two are joined at collection time. That is also why the in-guest metrics distinction matters for cost, since a StatsD counter exported by an agent on an instance becomes a custom metric with the agent's identity and dimension set attached to it, and each additional dimension multiplies what you are billed for.

Log filtering runs on the agent, before anything is published

The log filtering feature is described precisely. CloudWatch agent supports log filtering, where the agent processes each log message with the filters that you specify, and only publishes events that pass all filters to CloudWatch Logs.

The configuration is a JSON document with a filters array per file, and each filter is a type of include or exclude with a regular expression:

{
  "collect_list": [
    {
      "file_path": "/opt/aws/amazon-cloudwatch-agent/logs/test.log",
      "log_group_name": "test.log",
      "log_stream_name": "test.log",
      "filters": [
        {
          "type": "exclude",
          "expression": "Firefox"
        },
        {
          "type": "include",
          "expression": "P(UT|OST)"
        }
      ]
    }
  ]
}

The README shows the effect on a log file, and the three lines are worth reading because they demonstrate the semantics:

2021-09-27T19:36:35Z I! [logagent] Firefox Detected   // Agent excludes this 
2021-09-27T19:36:35Z POST (StatusCode: 200).  // Agent would push this to CloudWatch
2021-09-27T19:36:35Z GET (StatusCode: 400). // doesn't match regex, will be excluded

So the exclude filter removes anything containing Firefox, the include filter keeps only lines matching P(UT|OST), and the GET line is dropped because it does not match the include pattern. The combination is an allow list built from a deny list, which is the shape you want for a log file that is mostly noise.

Doing this on the agent rather than in CloudWatch Logs has a direct consequence for what you pay for, because filtered-out lines never leave the host.

Building from source and installing your own build

The README's build section starts with the prerequisites, which are Go, Go modules and rpm-build:

sudo yum install -y rpmdevtools rpm-build

Then there are two commands. Run `make build` to build the CloudWatch Agent for Linux, Debian and Windows environment, and run `make release` to build the agent, which also packages it into a RPM, DEB and ZIP package.

The release build produces a specific set of artefacts, and the README lists them:

build/bin/linux/arm64/amazon-cloudwatch-agent.rpm
build/bin/linux/amd64/amazon-cloudwatch-agent.rpm
build/bin/linux/arm64/amazon-cloudwatch-agent.deb
build/bin/linux/amd64/amazon-cloudwatch-agent.deb
build/bin/windows/amd64/amazon-cloudwatch-agent.zip
build/bin/darwin/amd64/amazon-cloudwatch-agent.tar.gz

Installing your own build is then a platform-specific set of commands. For the rpm package it is `rpm -Uvh amazon-cloudwatch-agent.rpm`, for the deb package `dpkg -i -E ./amazon-cloudwatch-agent.deb`, for Windows you unzip the zip and run `./install.ps1`, and for darwin you extract the tarball and copy the payload with `cp -rf ./opt/aws /opt` and the launch daemon with `cp -rf ./Library/LaunchDaemons/com.amazon.cloudwatch.agent.plist /Library/LaunchDaemons/`.

The make target table adds one more option worth noting. `dockerized-build` builds using a docker container without a local go environment, which is the path to take when the build host is not the machine you would normally install Go on. There are also Dockerfiles for the container image under amazon-cloudwatch-container-insights.

The Makefile's version handling has a fallback that matters for reproducible builds: the version comes from git describe, and in case of building outside of a git repo, the version presented in the CWAGENT_VERSION file is used as a fallback.

The go.mod shows which collector components AWS forked

The dependency file is the most revealing document in the repository, because it records exactly where AWS has diverged from upstream OpenTelemetry Collector.

The module is github.com/aws/amazon-cloudwatch-agent targeting go 1.26.0, and the first replacement swaps telegraf for an AWS fork:

replace github.com/influxdata/telegraf => github.com/aws/telegraf v0.10.2-0.20260929083507-8fa53b1b2aac

Then collectd is redirected to a maintained fork, and a group of collector components is redirected to amazon-contributing forks of the collector's contrib repository:

replace (
	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/awscloudwatchlogsexporter => github.com/amazon-contributing/opentelemetry-collector-contrib/exporter/awscloudwatchlogsexporter v0.0.0-20260928123001-54b8ee6518df
	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/awsemfexporter => github.com/amazon-contributing/opentelemetry-collector-contrib/exporter/awsemfexporter v0.0.0-20260928123001-54b8ee6518df
	github.com/open-telemetry/opentelemetry-collector-contrib/exporter/awsxrayexporter => github.com/amazon-contributing/opentelemetry-collector-contrib/exporter/awsxrayexporter v0.0.0-20260928123001-54b8ee6518df
)

The comment above that block explains the scope: there are no requirements for all receivers, processors and exporters to be replaced, since there are some changes that will always be from upstream. So the AWS forks are confined to the AWS-facing exporters and to the middleware and provisioning extensions, and everything else tracks upstream.

That is a well-scoped fork policy, and it has a practical consequence for anyone reading the code or upgrading. The AWS exporters are where the CloudWatch-specific behaviour lives, and the parts of the pipeline that are not AWS-specific are the upstream ones, which means an upstream collector change can affect this agent without AWS having published a release.

Usage data, security reporting and the licence terms

Two housekeeping items are worth knowing before you deploy the agent on a fleet.

The first is usage data. By default, the CloudWatch agent sends health and performance data about itself to CloudWatch whenever it publishes metrics or logs to CloudWatch, and the README states that this data incurs no costs to you. You can prevent it by specifying `false` for `usage_data` in the `agent` section of the configuration, and if you omit the parameter the default of true is used.

The second is how to report a vulnerability. If you think you have found a potential security issue, the README asks you not to post it in the Issues and instead to follow the AWS vulnerability reporting instructions or email AWS security directly. That is worth noting because an agent runs with the ability to read log files and system state on every host, which makes it a plausible target, and because a repository's issue tracker is the wrong place for a disclosure that needs a coordinated fix.

The licence is MIT, with two copyright lines, one for InfluxData Inc. covering 2015 to 2019 and one for Amazon.com, Inc. or its affiliates. The InfluxData line is a reminder of where the code came from, since telegraf was InfluxData's project before AWS took it over. The repository carries NOTICE and THIRD-PARTY files alongside the LICENSE, which is what you would expect for a binary that bundles telegraf, the collector and a set of plugins.

Versioning follows Semantic versioning, and the release numbers look unusual because they encode the upstream component versions, with the recent ones at v1.300073.0, v1.300072.0 and v1.300071.0. The official distributions are downloaded from S3 rather than from the repository's release artefacts, and the README points at the documentation link for the command line download.

Editorial conclusion

amazon-cloudwatch-agent fits an organisation that has already standardised on CloudWatch and wants one agent on EC2 and hybrid hosts rather than three separate collectors, especially where application metrics already arrive over StatsD. It is the wrong choice if you want to avoid the AWS ecosystem altogether, because the exporter side is AWS-shaped, and the wrong choice if you need a collector you can point at multiple backends, since the replacement directives in go.mod point the collector components at AWS forks. Verify first which of your metrics are in-guest rather than EC2 instance metrics, because the cost of collecting them differs, and read the usage_data setting, since the agent reports on itself by default unless you turn that off.

Frequently asked questions

Official sources

1. aws/amazon-cloudwatch-agent on GitHub
2. Issues
3. License: MIT
4. README
5. Releases