amazon/cloudwatch-agent

Amazon CloudWatch Agent Docker镜像

镜像概述

Amazon CloudWatch Agent Docker镜像是Amazon CloudWatch Agent的容器化部署版本。CloudWatch Agent是AWS提供的轻量级监控代理，用于收集系统、应用程序的指标与日志数据，并发送至Amazon CloudWatch服务，实现对AWS资源及应用的统一监控、告警与可观测性分析。

核心功能与特性

• 多源数据采集：支持收集系统指标（CPU、内存、磁盘I/O、网络）、应用程序指标（自定义指标）及日志数据（文件日志、标准输出日志等）。
• 容器环境适配：原生支持Kubernetes（含EKS）、Docker等容器环境，可采集容器级指标与Pod日志。
• 灵活配置：通过JSON配置文件自定义指标/日志采集规则、采样频率、数据发送目标等。
• CloudWatch集成：直接将数据发送至Amazon CloudWatch，支持与CloudWatch Metrics、Logs、Alarms等服务联动。
• 低资源占用：轻量级设计，对宿主系统资源消耗低，适合在资源受限的容器环境中运行。

使用场景与适用范围

• EC2容器监控：监控运行在EC2实例上的Docker容器，采集容器资源使用情况与应用日志。
• EKS/Kubernetes集群监控：部署于EKS或自管理Kubernetes集群，监控集群节点、Pod、服务的指标与日志（配合Container Insights）。
• 容器化应用可观测性：为微服务、容器化应用提供统一的指标与日志采集方案，支持问题排查与性能优化。
• AWS环境统一监控：与AWS其他服务（如ECS、Lambda）配合，构建端到端的监控体系。

使用方法与配置说明

获取镜像

CloudWatch Agent Docker镜像托管于Amazon ECR公共仓库，可通过以下命令拉取：

bash
docker pull public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest

注：可通过指定标签（如1.300025.0b253872）获取特定版本，版本列表参见https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/download-cloudwatch-agent-commandline.html%E3%80%82

配置文件准备

CloudWatch Agent通过JSON配置文件定义数据采集规则，核心包含metrics（指标配置）和logs（日志配置）模块。

配置文件示例（基础版）

创建config.json文件，示例内容如下：

json
{
  "agent": {
    "metrics_collection_interval": 60,
    "logfile": "/var/log/cloudwatch-agent.log"
  },
  "metrics": {
    "metrics_collected": {
      "cpu": {
        "resources": ["*"],
        "measurement": ["cpu_usage_idle", "cpu_usage_user", "cpu_usage_system"]
      },
      "mem": {
        "resources": ["*"],
        "measurement": ["mem_used_percent"]
      }
    }
  },
  "logs": {
    "logs_collected": {
      "files": {
        "collect_list": [
          {
            "file_path": "/var/log/application/*.log",
            "log_group_name": "/my-app/logs",
            "log_stream_name": "{instance_id}/application.log"
          }
        ]
      }
    }
  }
}

配置参数说明

• agent.metrics_collection_interval：指标采集间隔（秒），默认60秒。
• metrics.metrics_collected：定义需采集的指标类型（如cpu、mem、disk），resources: ["*"]表示采集所有资源（如所有CPU核心、磁盘分区）。
• logs.logs_collected.files.collect_list：定义日志文件路径、目标日志组（log_group_name）和日志流（log_stream_name）。

详细配置参数及高级功能（如自定义指标、过滤器）参见https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html%E3%80%82

运行容器（Docker Run）

前提条件

• 权限授权：容器需具备访问CloudWatch的权限，推荐通过以下方式之一：
  • EC2环境：为实例附加含CloudWatchAgentServerPolicy权限的IAM角色。
  • 非EC2环境：通过环境变量传入AWS凭证（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）。
• 目录挂载：需挂载宿主机日志目录（如/var/log）到容器内，确保Agent可访问日志文件。

基本运行命令

bash
docker run -d \
  --name cloudwatch-agent \
  --privileged \
  -v /var/run/docker.sock:/var/run/docker.sock \  # 用于Docker容器指标采集（可选）
  -v /sys:/sys \  # 用于系统指标采集
  -v /dev/disk/:/dev/disk \  # 用于磁盘指标采集（可选）
  -v /path/to/config.json:/etc/cloudwatch-agent-config.json \  # 挂载配置文件
  -e AWS_REGION=us-east-1 \  # 指定AWS区域
  public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest \
  /opt/aws/amazon-cloudwatch-agent/bin/start-amazon-cloudwatch-agent \
  --config-file /etc/cloudwatch-agent-config.json

非EC2环境（需传入凭证）

bash
docker run -d \
  --name cloudwatch-agent \
  --privileged \
  -v /path/to/config.json:/etc/cloudwatch-agent-config.json \
  -e AWS_REGION=us-east-1 \
  -e AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY \
  -e AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY \
  public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest \
  /opt/aws/amazon-cloudwatch-agent/bin/start-amazon-cloudwatch-agent --config-file /etc/cloudwatch-agent-config.json

Docker Compose配置示例

创建docker-compose.yml文件：

yaml
version: '3'
services:
  cloudwatch-agent:
    image: public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest
    container_name: cloudwatch-agent
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /sys:/sys
      - /dev/disk/:/dev/disk
      - ./config.json:/etc/cloudwatch-agent-config.json  # 挂载宿主机配置文件
    environment:
      - AWS_REGION=us-east-1
      # 非EC2环境需添加以下凭证
      # - AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
      # - AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
    command: /opt/aws/amazon-cloudwatch-agent/bin/start-amazon-cloudwatch-agent --config-file /etc/cloudwatch-agent-config.json
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

配置参数与环境变量

核心环境变量

配置文件路径

默认配置文件路径为容器内的/etc/cloudwatch-agent-config.json，需通过-v参数挂载宿主机配置文件至该路径。

参考文档

• https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html
• https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContainerInsights.html
• https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-Configuration-File-Details.html
• ECR公共仓库镜像信息