name: aws-ecs-monitor
version: 1.0.1
description: AWS ECS 生产环境健康监控与 CloudWatch 日志分析工具 —— 监控 ECS 服务健康状态、ALB 目标组、SSL 证书，并提供深入的 CloudWatch 日志分析，用于错误分类、重启检测和生产告警。
metadata:
openclaw:
requires:
bins: ["aws", "curl", "python3"]
anyBins: ["openssl"]

AWS ECS 监控工具

用于 AWS ECS 服务的生产环境健康监控与日志分析。

功能概述

• 健康检查：对您的域名进行 HTTP 探测，检查 ECS 服务状态（期望 vs 运行中）、ALB 目标组健康状态、SSL 证书过期情况。
• 日志分析：拉取 CloudWatch 日志，对错误进行分类（panic、fatal、OOM、超时、5xx 错误），检测容器重启，过滤健康检查噪声。
• 自动诊断：读取健康状态，并通过日志分析自动调查故障服务。

前置要求

• 已配置 aws CLI 并具备相应 IAM 权限：
• ecs:ListServices, ecs:DescribeServices
• elasticloadbalancing:DescribeTargetGroups, elasticloadbalancing:DescribeTargetHealth
• logs:FilterLogEvents, logs:DescribeLogGroups
• curl：用于 HTTP 健康检查。
• python3：用于 JSON 处理和日志分析。
• openssl：用于 SSL 证书检查（可选）。

配置

所有配置均通过环境变量进行：

写入的目录

• ECS_HEALTH_STATE（默认：./data/ecs-health.json）—— 健康状态 JSON 文件。
• ECS_HEALTH_OUTDIR（默认：./data/）—— 日志、告警和分析报告的输出目录。

脚本

scripts/ecs-health.sh —— 健康监控器

# 完整检查
ECS_CLUSTER=my-cluster ECS_DOMAIN=example.com ./scripts/ecs-health.sh

# 仅 JSON 输出
ECS_CLUSTER=my-cluster ./scripts/ecs-health.sh --json

# 静默模式（无告警，仅更新状态文件）
ECS_CLUSTER=my-cluster ./scripts/ecs-health.sh --quiet

退出码：0 = 健康，1 = 不健康/降级，2 = 脚本错误

scripts/cloudwatch-logs.sh —— 日志分析器

# 从服务拉取原始日志
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh pull my-api --minutes 30

# 显示所有服务的错误
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh errors all --minutes 120

# 深度分析，包含错误分类
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh diagnose --minutes 60

# 检测容器重启
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh restarts my-api

# 根据健康状态文件自动诊断
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh auto-diagnose

# 所有服务的汇总报告
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh summary --minutes 120

选项：--minutes N（默认：60）、--json、--limit N（默认：200）、--verbose

自动检测

当未设置 ECS_SERVICES 时，两个脚本都会从集群自动检测服务：

aws ecs list-services --cluster $ECS_CLUSTER

日志组通过模式解析（默认 /ecs/{service}）。可通过 ECS_LOG_PATTERN 覆盖：

# 如果您的日志组是 /ecs/prod/my-api, /ecs/prod/my-frontend 等
ECS_LOG_PATTERN="/ecs/prod/{service}" ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh diagnose

集成

健康监控器在检测到问题时可以触发日志分析器进行自动诊断。将 ECS_HEALTH_OUTDIR 设置为共享目录，并同时运行两个脚本：

export ECS_CLUSTER=my-cluster
export ECS_DOMAIN=example.com
export ECS_HEALTH_OUTDIR=./data

# 运行健康检查（失败时自动触发日志分析）
./scripts/ecs-health.sh

# 或独立运行日志分析
./scripts/cloudwatch-logs.sh auto-diagnose --minutes 30

错误分类

日志分析器将错误分类为：

• panic —— Go panic
• fatal —— 致命错误
• oom —— 内存不足
• timeout —— 连接/请求超时
• connection_error —— 连接被拒绝/重置
• http_5xx —— HTTP 5xx 响应
• python_traceback —— Python 回溯
• exception —— 通用异常
• auth_error —— 权限/授权失败
• structured_error —— JSON 结构化的错误日志
• error —— 通用的 ERROR 级别消息

健康检查噪声（来自 ALB 的 GET/HEAD /health 请求）会自动从错误计数和 HTTP 状态分布中过滤掉。