cw-debug

/cw-debug — CloudWatch Log Investigation Skill

You are investigating a production issue using CloudWatch Logs Insights. Follow the structured methodology below, adapting queries based on what you discover in each phase.

Arguments

The user will invoke this skill as:

/cw-debug <log_group> <filter_pattern> <hours_back> <region> "<issue_description>"

• log_group: The CloudWatch log group path (e.g., /aws/ecs/my-service)
• filter_pattern: Any string to filter logs — a user ID, request ID, service name, error code, or any identifier relevant to the investigation
• hours_back: How many hours of logs to search (e.g., 24, 168 for 7 days)
• region: AWS region (e.g., us-east-1)
• issue_description: Free-text description of the problem being investigated (bug, performance issue, unexpected behavior, etc.)

Setup

• Always use .venv/bin/python to run scripts
• The skill has its own self-contained CloudWatch utility at ${CLAUDE_PLUGIN_ROOT}/skills/cw-debug/scripts/cw.py
• Do NOT import from cloudwatch_utils.py — use the skill's own module instead
• To use in inline scripts, add the scripts dir to sys.path then import:

  import sys, os
  sys.path.insert(0, os.path.expanduser("${CLAUDE_PLUGIN_ROOT}/skills/cw-debug/scripts"))
  from cw import CWClient
  
  cw = CWClient(region="{region}")
  results = cw.query("{query}", hours_back={hours_back}, log_group="{log_group}")
  cw.print_table(results)
  

• Or use the CLI directly:

  .venv/bin/python ${CLAUDE_PLUGIN_ROOT}/skills/cw-debug/scripts/cw.py \
      --region {region} --log-group "{log_group}" --hours {hours_back} \
      --query "fields @timestamp, @message | limit 25"
  

• Available CWClient methods:
  • cw.query(query_string, hours_back, log_group) — single log group query
  • cw.query_multi(query_string, hours_back, log_groups) — query multiple log groups, merge results with _log_group tag
  • CWClient.summarize_stats(results, value_field, group_field=None) — compute count/avg/min/p50/p90/p95/p99/max from fetched results
  • CWClient.time_bucket_counts(results, timestamp_field, bucket_minutes) — group into time buckets for spike detection
  • CWClient.print_table(results) — ASCII table output
  • CWClient.print_json(results) — JSON output
  • cw.save(results, name) — save to investigations/<name>.csv
• Refer to ${CLAUDE_PLUGIN_ROOT}/skills/cw-debug/query_library.md for pre-built query templates