🎁 Get the FREE AI Skills Starter Guide — Subscribe →
BytesAgainBytesAgain
BytesAgain › Skills › aws-ecs-monitor
🦀 ClawHub

aws-ecs-monitor

by @briancolinger

AWS ECS production health monitoring with CloudWatch log analysis — monitors ECS service health, ALB targets, SSL certificates, and provides deep CloudWatch...

Versionv1.0.1
Downloads2,916
#devops#legal#health
TERMINAL
clawhub install aws-ecs-monitor

📖 About This Skill

name: aws-ecs-monitor version: 1.0.1 description: AWS ECS production health monitoring with CloudWatch log analysis — monitors ECS service health, ALB targets, SSL certificates, and provides deep CloudWatch log analysis for error categorization, restart detection, and production alerts. metadata: openclaw: requires: bins: ["aws", "curl", "python3"] anyBins: ["openssl"]

AWS ECS Monitor

Production health monitoring and log analysis for AWS ECS services.

What It Does

  • Health Checks: HTTP probes against your domain, ECS service status (desired vs running), ALB target group health, SSL certificate expiry
  • Log Analysis: Pulls CloudWatch logs, categorizes errors (panics, fatals, OOM, timeouts, 5xx), detects container restarts, filters health check noise
  • Auto-Diagnosis: Reads health status and automatically investigates failing services via log analysis

    • Prerequisites

  • aws CLI configured with appropriate IAM permissions:
    • - ecs:ListServices, ecs:DescribeServices - elasticloadbalancing:DescribeTargetGroups, elasticloadbalancing:DescribeTargetHealth - logs:FilterLogEvents, logs:DescribeLogGroups
  • curl for HTTP health checks
  • python3 for JSON processing and log analysis
  • openssl for SSL certificate checks (optional)

    • Configuration

    All configuration is via environment variables:

    | Variable | Required | Default | Description | |---|---|---|---| | ECS_CLUSTER | Yes | — | ECS cluster name | | ECS_REGION | No | us-east-1 | AWS region | | ECS_DOMAIN | No | — | Domain for HTTP/SSL checks (skip if unset) | | ECS_SERVICES | No | auto-detect | Comma-separated service names to monitor | | ECS_HEALTH_STATE | No | ./data/ecs-health.json | Path to write health state JSON | | ECS_HEALTH_OUTDIR | No | ./data/ | Output directory for logs and alerts | | ECS_LOG_PATTERN | No | /ecs/{service} | CloudWatch log group pattern ({service} is replaced) | | ECS_HTTP_ENDPOINTS | No | — | Comma-separated name=url pairs for HTTP probes |

    Directories Written

  • ECS_HEALTH_STATE (default: ./data/ecs-health.json) — Health state JSON file
  • ECS_HEALTH_OUTDIR (default: ./data/) — Output directory for logs, alerts, and analysis reports

    • Scripts

    scripts/ecs-health.sh — Health Monitor

    # Full check
ECS_CLUSTER=my-cluster ECS_DOMAIN=example.com ./scripts/ecs-health.sh
    JSON output only
    
ECS_CLUSTER=my-cluster ./scripts/ecs-health.sh --json
    Quiet mode (no alerts, just status file)
    
ECS_CLUSTER=my-cluster ./scripts/ecs-health.sh --quiet

    Exit codes: 0 = healthy, 1 = unhealthy/degraded, 2 = script error

    scripts/cloudwatch-logs.sh — Log Analyzer

    # Pull raw logs from a service
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh pull my-api --minutes 30
    Show errors across all services
    
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh errors all --minutes 120
    Deep analysis with error categorization
    
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh diagnose --minutes 60
    Detect container restarts
    
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh restarts my-api
    Auto-diagnose from health state file
    
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh auto-diagnose
    Summary across all services
    
ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh summary --minutes 120

    Options: --minutes N (default: 60), --json, --limit N (default: 200), --verbose

    Auto-Detection

    When ECS_SERVICES is not set, both scripts auto-detect services from the cluster:

    aws ecs list-services --cluster $ECS_CLUSTER

    Log groups are resolved by pattern (default /ecs/{service}). Override with ECS_LOG_PATTERN:

    # If your log groups are /ecs/prod/my-api, /ecs/prod/my-frontend, etc.
ECS_LOG_PATTERN="/ecs/prod/{service}" ECS_CLUSTER=my-cluster ./scripts/cloudwatch-logs.sh diagnose

    Integration

    The health monitor can trigger the log analyzer for auto-diagnosis when issues are detected. Set ECS_HEALTH_OUTDIR to a shared directory and run both scripts together:

    export ECS_CLUSTER=my-cluster
export ECS_DOMAIN=example.com
export ECS_HEALTH_OUTDIR=./data
    Run health check (auto-triggers log analysis on failure)
    
./scripts/ecs-health.sh
    Or run log analysis independently
    
./scripts/cloudwatch-logs.sh auto-diagnose --minutes 30

    Error Categories

    The log analyzer classifies errors into:

  • panic — Go panics
  • fatal — Fatal errors
  • oom — Out of memory
  • timeout — Connection/request timeouts
  • connection_error — Connection refused/reset
  • http_5xx — HTTP 500-level responses
  • python_traceback — Python tracebacks
  • exception — Generic exceptions
  • auth_error — Permission/authorization failures
  • structured_error — JSON-structured error logs
  • error — Generic ERROR-level messages

    • Health check noise (GET/HEAD /health from ALB) is automatically filtered from error counts and HTTP status distribution.

    ⚙️ Configuration

    All configuration is via environment variables:

    | Variable | Required | Default | Description | |---|---|---|---| | ECS_CLUSTER | Yes | — | ECS cluster name | | ECS_REGION | No | us-east-1 | AWS region | | ECS_DOMAIN | No | — | Domain for HTTP/SSL checks (skip if unset) | | ECS_SERVICES | No | auto-detect | Comma-separated service names to monitor | | ECS_HEALTH_STATE | No | ./data/ecs-health.json | Path to write health state JSON | | ECS_HEALTH_OUTDIR | No | ./data/ | Output directory for logs and alerts | | ECS_LOG_PATTERN | No | /ecs/{service} | CloudWatch log group pattern ({service} is replaced) | | ECS_HTTP_ENDPOINTS | No | — | Comma-separated name=url pairs for HTTP probes |