如何从应用程序向CloudWatch Agent发送自定义指标数据

前置依赖配置 #

• 给运行Agent的资源（EC2实例、EKS工作节点等）绑定包含CloudWatchAgentServerPolicyAWS托管策略的IAM角色，确保Agent有上报指标的权限。

安装CloudWatch Agent #

根据你的操作系统选择对应安装方式：

• Amazon Linux 2/2023：执行sudo amazon-linux-extras install amazon-cloudwatch-agent
• Debian/Ubuntu系列：先导入AWS公钥、添加CloudWatch Agent源后执行sudo apt install amazon-cloudwatch-agent
• RHEL/CentOS系列：添加AWS yum源后执行sudo yum install amazon-cloudwatch-agent

自定义指标采集配置（两种常用方案二选一即可） #

方案1：应用通过StatsD协议主动推送指标（推荐，改造成本低） #

CloudWatch Agent原生支持StatsD协议作为接收端，你只需要在业务应用中集成对应语言的StatsD客户端，把指标推给本地Agent的8125端口即可，无需自己调用CloudWatch API。
Agent配置文件示例（路径默认是/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json）：

{
  "metrics": {
    "namespace": "BusinessApp/CustomMetrics",
    "metrics_collected": {
      "statsd": {
        "service_address": ":8125",
        "metrics_aggregation_interval": 60,
        "metrics_collection_interval": 60
      }
    },
    "append_dimensions": {
      "InstanceId": "${aws:InstanceId}",
      "AppName": "your-business-app"
    }
  }
}

应用侧代码示例（以Python为例）：

1. 先安装StatsD客户端：pip install statsd
2. 上报指标代码：

import statsd
# 初始化客户端，默认连接本地8125端口
statsd_client = statsd.StatsClient('localhost', 8125)
# 上报连接数（gauge类型，数值可增可减）
statsd_client.gauge('connection_count', 132)
# 上报队列长度
statsd_client.gauge('queue_length', 27)

Agent会自动将收到的StatsD指标聚合后批量上报到CloudWatch。

方案2：Agent定时拉取指标（适合无法修改应用代码的场景） #

你可以自己编写一个脚本（Shell/Python等都可以），脚本执行后输出符合CloudWatch Agent格式的指标数据，Agent定时执行脚本拉取指标上报。

1. 自定义脚本示例（路径比如/opt/scripts/get_app_metrics.sh，记得加执行权限）：

#!/bin/bash
# 这里替换为你自己的获取连接数、队列数的逻辑
CONN_COUNT=$(ss -tulnp | grep your_app_port | wc -l)
QUEUE_COUNT=$(cat /tmp/app_queue_length 2>/dev/null || echo 0)
# 输出指定格式的指标
echo "[{\"metric\": \"connection_count\", \"value\": $CONN_COUNT, \"unit\": \"Count\"}, {\"metric\": \"queue_length\", \"value\": $QUEUE_COUNT, \"unit\": \"Count\"}]"

2. Agent配置文件示例：

{
  "metrics": {
    "namespace": "BusinessApp/CustomMetrics",
    "metrics_collected": {
      "exec": {
        "commands": ["/opt/scripts/get_app_metrics.sh"],
        "metrics_collection_interval": 60
      }
    },
    "append_dimensions": {
      "InstanceId": "${aws:InstanceId}",
      "AppName": "your-business-app"
    }
  }
}

启动Agent并验证 #

执行命令加载配置并启动Agent：
sudo amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -c file:/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.json -s
验证方式：

• 查看Agent运行日志/var/log/amazon/amazon-cloudwatch-agent/amazon-cloudwatch-agent.log确认无报错
• 登录CloudWatch控制台，在对应区域的「指标」-「自定义命名空间」下找到你配置的BusinessApp/CustomMetrics命名空间，即可看到上报的连接数、队列数指标

注意事项 #

• 你可以根据业务需要调整指标采集间隔，最低支持10秒上报一次，注意合理设置避免产生过多CloudWatch指标费用
• 建议提前规划指标维度，比如增加环境（生产/测试）、服务模块等维度，方便后续指标聚合筛选
• 如果是容器环境部署，Agent可以以DaemonSet形式运行，采集配置逻辑和EC2环境完全一致

内容的提问来源于stack exchange，提问作者Jijo John