Amazon CloudWatch agent

The CloudWatch agent is built on the OpenTelemetry Collector, so you can use it to receive OpenTelemetry data and send it to the CloudWatch OTLP endpoints. In most cases, this is the recommended way to send OpenTelemetry data to CloudWatch, because a single agent can also power curated experiences such as CloudWatch Application Signals and CloudWatch Enhanced Container Insights.

You can configure the agent to send OpenTelemetry data to the CloudWatch OTLP endpoints in two ways:

Send OpenTelemetry data using the agent configuration file

Add an opentelemetry section to your CloudWatch agent configuration file and include the otlp source under collect. When the agent starts with this configuration, it listens for OTLP data and forwards the received metrics, logs, and traces to the CloudWatch OTLP endpoints. For the fields you can set and their defaults, see Manually create or edit the CloudWatch agent configuration file.

The following example configures the agent to receive OTLP data over gRPC and HTTP.

{
  "opentelemetry": {
    "collect": {
      "otlp": {
        "grpc_endpoint": "0.0.0.0:4317",
        "http_endpoint": "0.0.0.0:4318"
      }
    }
  }
}

Start the agent with this configuration the same way as any other agent configuration file.

/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -c file:/tmp/agent.json -s

Append an OpenTelemetry collector configuration in YAML

For pipelines that the agent configuration file does not expose, you can append an OpenTelemetry collector configuration in YAML. Start the agent with your CloudWatch agent configuration file, then append the OpenTelemetry YAML file:

/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -c file:/tmp/agent.json -s
/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/tmp/otel.yaml -s

The agent merges the two configurations on startup and logs the resolved configuration. To avoid merge conflicts with pipelines that the agent creates automatically, add a custom suffix to each component and pipeline name in your OpenTelemetry YAML (for example, otlphttp/cwagent).

Supported OpenTelemetry components

The following OpenTelemetry components are available for you to configure in your appended YAML configuration. Use the component type name shown here as the key in your YAML.

The CloudWatch agent only supports writing telemetry to AWS destinations.

Configuration examples

The following examples send each signal to the corresponding CloudWatch OTLP endpoint using the otlphttp exporter and the sigv4auth extension. Each component and pipeline name uses a /cwagent suffix to avoid conflicts with pipelines that the agent creates automatically. Replace region with your AWS Region.

Metrics

receivers:
  otlp/cwagent:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
processors:
  batch/cwagent: {}
exporters:
  otlphttp/cwagent:
    metrics_endpoint: https://monitoring.region.amazonaws.com/v1/metrics
    auth:
      authenticator: sigv4auth/cwagent
extensions:
  sigv4auth/cwagent:
    region: "region"
    service: "monitoring"
service:
  extensions: [sigv4auth/cwagent]
  pipelines:
    metrics/cwagent:
      receivers: [otlp/cwagent]
      processors: [batch/cwagent]
      exporters: [otlphttp/cwagent]

Logs

receivers:
  otlp/cwagent:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
exporters:
  otlphttp/cwagent:
    logs_endpoint: https://logs.region.amazonaws.com/v1/logs
    headers:
      x-aws-log-group: my-log-group
      x-aws-log-stream: default
    auth:
      authenticator: sigv4auth/cwagent
extensions:
  sigv4auth/cwagent:
    region: "region"
    service: "logs"
service:
  extensions: [sigv4auth/cwagent]
  pipelines:
    logs/cwagent:
      receivers: [otlp/cwagent]
      exporters: [otlphttp/cwagent]

Traces

receivers:
  otlp/cwagent:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
exporters:
  otlphttp/cwagent:
    traces_endpoint: https://xray.region.amazonaws.com/v1/traces
    auth:
      authenticator: sigv4auth/cwagent
extensions:
  sigv4auth/cwagent:
    region: "region"
    service: "xray"
service:
  extensions: [sigv4auth/cwagent]
  pipelines:
    traces/cwagent:
      receivers: [otlp/cwagent]
      exporters: [otlphttp/cwagent]

Example: send application metrics through the agent without a separate collector

This example shows how to send application metrics to the CloudWatch OpenTelemetry Protocol (OTLP) endpoints through the CloudWatch agent, from an application that is instrumented with an OpenTelemetry SDK. Your application exports OTLP to the agent that runs alongside it, and the agent forwards the metrics to CloudWatch. You do not run a separate collector to do this.

Prerequisites

Before you begin, make sure that you have the following:

Common steps

The following steps are the same regardless of where the agent runs.

Amazon EC2

Run the CloudWatch agent on the Amazon EC2 instance, and configure your application to export OTLP to the agent on the same instance. Set the application's OTLP exporter endpoint to http://localhost:4317 for gRPC or http://localhost:4318 for HTTP. The agent forwards the metrics to the CloudWatch OTLP endpoints.

Amazon ECS

On Amazon ECS, run the CloudWatch agent as a sidecar container in the same task as your application, or as a daemon service on each container instance. When the agent runs as a sidecar, your application exports OTLP to localhost within the task (port 4317 for gRPC or port 4318 for HTTP). When the agent runs as a daemon service, your application exports OTLP to the agent on the host. In both cases, the agent forwards the metrics to the CloudWatch OTLP endpoints.

Amazon EKS

On Amazon EKS, install or upgrade the CloudWatch Observability EKS add-on to version 6.6.0 or later. The add-on runs the CloudWatch agent in your cluster. Earlier versions do not expose the OTLP ports on the agent Service.

You must also supply the agent opentelemetry and otlp configuration to the add-on through its configuration values. The add-on does not enable the OTLP receiver by default. Supply the following configuration values to the add-on.

{
  "agent": {
    "config": {
      "opentelemetry": {
        "collect": {
          "otlp": {
            "grpc_endpoint": "0.0.0.0:4317",
            "http_endpoint": "0.0.0.0:4318"
          }
        }
      }
    }
  }
}

After the add-on rolls out, the cloudwatch-agent Service exposes ports 4317 and 4318. Your application pods export OTLP to the agent Service, and the agent forwards the metrics to the CloudWatch OTLP endpoints.