CloudWatch Exporter

通过CloudWatch API拉取云产品的监控指标，暴露为Prometheus标准格式，实现云产品监控数据与Prometheus生态的对接。

注意事项

⚠️ 出于安全考虑，建议不要把exporter开放到公网。

1. 构建

需要 Go 1.25 及以上版本，从源码构建 Linux amd64 静态二进制：

make build

产出 bin/cloudwatch-exporter（CGO_ENABLED=0，静态编译）。

2. 配置

编辑 config.toml，填写以下必填项：

[server]
listen         = ":9105"       # Exporter HTTP 监听地址
metrics_path   = "/metrics"    # Prometheus 拉取路径

[data_source]
endpoint       = "https://api.ucloud.cn"   # CloudWatch API 网关地址
timeout_ms     = 30000                       # 单次请求超时（毫秒），最低 10s
concurrency    = 20                         # 后台轮询并发数，上限 20

[credential]
public_key     = "YOUR_PUBLIC_KEY"          # 公钥（可通过环境变量 PUBLIC_KEY 传入）
private_key    = "YOUR_PRIVATE_KEY"         # 私钥（可通过环境变量 PRIVATE_KEY 传入）

[log]
level         = "info"      # 日志级别: debug, info, warn, error
file          = "stdout"    # 日志文件路径，"stdout" 则输出到标准输出
max_size      = 10          # 单个日志文件最大大小（MB）
max_backups   = 7           # 保留的旧日志文件最大数量
max_age       = 7           # 保留的旧日志文件最大天数
compress      = false       # 是否压缩旧日志文件

[poller]
stale_multiplier = 3    # 过期倍数（超过 采集间隔(指标数据上报频率) * multiplier 未更新则停止暴露）

# 采集配置（可配置多个）
[[scrape]]
project_id   = "org-xxxxxx"                # 项目 ID（必填）
region       = "cn-bj2"                    # 地域（必填）
product_key  = "uhost"                     # 产品标识
resource_ids  = ["uhost-xxx", "uhost-yyy"]  # 资源 ID 列表（all_resource_id=false 时必填）
all_resource_id = false                     # 自动获取该产品下所有资源时为 true，此时 resource_ids 可不填
metrics      = ["uhost_cpu_used"]          # 指标名称列表（all_metrics=false 时必填）
all_metrics  = false                       # 导出所有指标时为 true，此时 metrics 可不填

获取凭证： public_key 和 private_key 可从 API 密钥管理 获取。

product_key 产品标识见 CloudWatch 指标参考。

环境变量（可选）

支持通过环境变量传入凭证，优先级高于配置文件：

export PUBLIC_KEY="your_public_key"
export PRIVATE_KEY="your_private_key"

配置说明

服务配置 ([server])

字段	必填	默认	说明
listen	是	:9105	Exporter HTTP 监听地址
metrics_path	是	/metrics	Prometheus 拉取路径

API 配置 ([data_source])

字段	必填	默认	说明
endpoint	是	—	CloudWatch API 网关地址
timeout_ms	否	30000	单次请求超时（毫秒），最低 10s
concurrency	否	20	后台轮询并发数，上限 20

单批请求数固定为 10（CloudWatch API 限制单次最多 10 个 series），代码中自动分批处理。

凭证配置 ([credential])

字段	必填	默认	说明
public_key	否	—	公钥，支持环境变量 PUBLIC_KEY
private_key	否	—	私钥，支持环境变量 PRIVATE_KEY

日志配置 ([log])

字段	必填	默认	说明
level	否	info	日志级别: debug, info, warn, error
file	否	stdout	日志文件路径，stdout 或留空则输出到标准输出
max_size	否	10	单个日志文件最大大小（MB）
max_backups	否	7	保留的旧日志文件最大数量
max_age	否	7	保留的旧日志文件最大天数
compress	否	false	是否压缩旧日志文件

max_size、max_backups、max_age、compress 仅在 file 不为 stdout 时生效。

轮询配置 ([poller])

采集间隔由 GetProductMetrics API 返回的指标上报频率自动决定，不同频率的指标分为独立轮询组各自采集。

字段	必填	默认	说明
stale_multiplier	否	3	过期倍数，超过 采集间隔 × multiplier 未更新则停止暴露

采集配置 ([[scrape]])

每个 [[scrape]] 块代表一组采集任务（至少配置一个）：

字段	必填	默认	说明
project_id	是	—	项目 ID
region	是	—	地域标识
product_key	是	—	产品标识，如 uhost
resource_ids	条件必填	—	资源 ID 列表，all_resource_id=false 时必填
all_resource_id	否	false	设为 true 自动获取该产品下所有资源，此时 resource_ids 可不填
metrics	条件必填	—	指标名称列表，all_metrics=false 时必填
all_metrics	否	false	设为 true 自动导出该产品所有支持指标，此时 metrics 可不填
label_aliases	否	—	label 别名映射，{ 源 label 名 = 输出 label 名 }。源名大小写敏感，须与上游 TagMap 的 key 或内置 label 名完全一致；详见 README

3. 启动

# 直接启动
./cloudwatch-exporter -c config.toml

# 指定端口
./cloudwatch-exporter -c config.toml -p 9106

# 通过环境变量传入凭证并启动
PUBLIC_KEY=your_public_key PRIVATE_KEY=your_private_key \
  ./cloudwatch-exporter -c config.toml

启动参数：

参数	默认	说明
-c	config.toml	配置文件路径
-p	配置文件中的值	监听端口，覆盖配置文件

启动日志示例（凭证已自动遮蔽）：

[INFO] config loaded: endpoint=https://api.ucloud.cn, scrape_items=1, credential=PublicKey=4Dx6***, PrivateKey=***
[INFO] poller started with 1 scrape items
[INFO] cloudwatch collector registered
[INFO] server listening on :9105/metrics (metrics) and :9105/self/metrics (self-monitoring)

4. 验证

访问 metrics 端点，查看暴露的指标：

curl http://localhost:9105/metrics

输出示例：

# HELP uhost_cpu_used Cloud cloud metric
# TYPE uhost_cpu_used gauge
uhost_cpu_used{product_key="uhost",resource_id="uhost-xxx",resource_name="test-host",region="cn-bj2",project_id="org-xxxxxx"} 45.5 1720857600000

指标名与配置中的 metrics 名称一致，标签默认包含 product_key、resource_id、resource_name、resource_remark、region、project_id，以及上游 TagMap 动态标签。上游 TagMap 的 key 原样透传，需要改名或归一化时用 label 别名。

5. Prometheus 接入

在 Prometheus 配置文件中添加抓取目标（job_name 根据实际场景自定义）：

scrape_configs:
  - job_name: '<your-job-name>'
    static_configs:
      - targets: ['<exporter-ip>:9105']