Monitoring

---
name: monitoring
description: "Set up application observability with Prometheus, Grafana, Datadog, or CloudWatch — instrument metrics endpoints, configure Golden Signal dashboards, define alert rules with burn-rate SLOs, and add structured logging"
version: "2.0.0"
category: deploy
platforms:
  - CLAUDE_CODE
---

You are in AUTONOMOUS MODE. Do NOT ask questions. Do NOT pause for confirmation.
Execute every phase below in sequence, making decisions based on what you find.

============================================================
PHASE 0 — INPUT
============================================================

$ARGUMENTS may contain:
- A monitoring stack: `prometheus`, `datadog`, `cloudwatch`, `newrelic`, `grafana`
- `--instrument` — add application-level metrics instrumentation to source code
- `--alerts-only` — generate alerting rules without full dashboard setup
- `--slo` — define and configure SLO/SLI targets with burn-rate alerts
- A specific focus: `latency`, `errors`, `traffic`, `saturation`
- If no arguments, auto-detect existing monitoring and extend it, or default to Prometheus + Grafana

============================================================
PHASE 1 — INFRASTRUCTURE DETECTION
============================================================

Scan for existing monitoring setup:

**Prometheus ecosystem**:
- `prometheus.yml`, `prometheus/` directory
- `alertmanager.yml`, `alertmanager/` directory
- Grafana dashboards: `grafana/`, `dashboards/`, `*.json` with `"panels"` key
- Docker compose services named `prometheus`, `grafana`, `alertmanager`

**Cloud-native**:
- AWS: CloudWatch references in Terraform, `aws_cloudwatch_*` resources
- GCP: Cloud Monitoring, `google_monitoring_*` resources
- Azure: Application Insights, `azurerm_monitor_*` resources

**Third-party**:
- Datadog: `datadog.yaml`, `DD_*` environment variables, `datadog-agent` in compose
- New Relic: `.newrelic.yml`, `NEW_RELIC_*` env vars, `newrelic` in dependencies
- Sentry: `sentry.properties`, `SENTRY_DSN` in env, `@sentry/*` in deps

**Application stack**:
- Node.js: check for `prom-client`, `express-prometheus-middleware`, `@opentelemetry/*`
- Python: check for `prometheus_client`, `django-prometheus`, `opentelemetry-*`
- Go: check for `prometheus/client_golang`, `go.opentelemetry.io`
- Java: check for Micrometer, Spring Actuator

**Infrastructure**:
- Kubernetes: check for ServiceMonitor CRDs, Prometheus Operator
- Docker: check compose services for metrics endpoints
- Serverless: check for X-Ray, CloudWatch Logs

============================================================
PHASE 2 — METRICS DESIGN (Golden Signals)
============================================================

Design metrics based on the Four Golden Signals:

**1. Latency** — time to service a request
- `http_request_duration_seconds` (histogram)
- Buckets: 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10
- Track by: method, route, status_code
- Report P50, P90, P95, P99 percentiles

**2. Traffic** — demand on the system
- `http_requests_total` (counter)
- Track by: method, route, status_code
- Report requests per second

**3. Errors** — rate of failed requests
- `http_errors_total` (counter) — 5xx responses
- `http_client_errors_total` (counter) — 4xx responses
- Error rate = errors / total requests

**4. Saturation** — how full the service is
- CPU utilization, memory usage
- Connection pool usage (database, Redis)
- Queue depth (if applicable)
- Event loop lag (Node.js)
- GC pause time (Java, Go)

============================================================
PHASE 3 — APPLICATION INSTRUMENTATION (if --instrument)
============================================================

Add metrics middleware to the application:

**Node.js (Express/Fastify)**:
- Install `prom-client` dependency
- Create metrics middleware tracking `http_request_duration_seconds` and `http_requests_total`
- Add `/metrics` endpoint exposing Prometheus format
- Add default Node.js process metrics (memory, CPU, event loop)

**Python (FastAPI/Django)**:
- Install `prometheus_client` or `prometheus-fastapi-instrumentator`
- Expose `/metrics` endpoint
- Add middleware for request duration tracking

**Go**:
- Add `promhttp.Handler()` on `/metrics`
- Use `promauto` for auto-registering metrics
- Add middleware using `promhttp.InstrumentHandlerDuration`

Also add to the application:
- **Health endpoints**: `/health` (liveness), `/ready` (readiness)
- **Version endpoint**: `/version` returning app version and build info
- **Structured logging**: ensure logs are JSON-formatted with correlation IDs

============================================================
PHASE 4 — PROMETHEUS + GRAFANA SETUP
============================================================

If using Prometheus stack, generate:

**`monitoring/prometheus/prometheus.yml`**:
- Global scrape interval: 15s, evaluation interval: 15s
- Rule files referencing `alerts/*.yml`
- Scrape config targeting `app:{port}` on `/metrics` with 10s interval

**`monitoring/prometheus/alerts/app.yml`**:
Alert rules (all with `for` duration to prevent flapping):
- `HighErrorRate`: `rate(http_errors_total[5m]) / rate(http_requests_total[5m]) > 0.01` for 5m (critical)
- `HighLatency`: P99 > 2s for 5m (warning)
- `HighMemoryUsage`: > 512MB for 10m (warning)
- `HighCPU`: > 80% for 10m (warning)
- `DiskUsageHigh`: > 80% for 5m (warning)
- `ServiceDown`: `up == 0` for 1m (critical)

**`monitoring/grafana/dashboards/app.json`**:
Grafana dashboard JSON with panels:
1. Request Rate (by status code)
2. Error Rate (percentage over time)
3. Latency Distribution (heatmap)
4. P50/P90/P99 Latency (time series)
5. Active Connections (gauge)
6. Memory Usage (time series)
7. CPU Usage (time series)
8. Saturation (connection pool, queue depth)

**`monitoring/grafana/provisioning/dashboards.yml`**: File-based dashboard provisioning.

**Docker Compose** (`monitoring/docker-compose.monitoring.yml`):
- Prometheus v2.51+ with 30d retention
- Grafana 10.4+ with provisioned dashboards and datasources
- Alertmanager v0.27+ for notification routing
- All with proper volume mounts and health checks

============================================================
PHASE 5 — CLOUD MONITORING (if Datadog/CloudWatch/New Relic)
============================================================

**Datadog**:
- Generate `datadog.yaml` agent config
- Add `dd-trace` to application dependencies
- Configure APM, log collection, custom metrics
- Generate monitor definitions in JSON

**CloudWatch**:
- Generate Terraform for CloudWatch alarms, dashboards, log groups
- Configure metric filters on log groups
- Set up SNS topics for alarm notifications

**New Relic**:
- Generate `newrelic.yml` configuration
- Add agent to application dependencies
- Configure custom dashboards via NR API (NRQL queries)

============================================================
PHASE 6 — SLO CONFIGURATION (if --slo)
============================================================

Define SLOs based on service type:

- **Availability SLO**: 99.9% uptime (43.8 min/month error budget)
- **Latency SLO**: 95% of requests < 200ms, 99% < 1s
- **Error SLO**: < 0.1% error rate

Generate burn rate alerts:
- Fast burn (2%/hour): page immediately — requires human attention within minutes
- Slow burn (5%/day): ticket within 1 hour — investigate during business hours


============================================================
SELF-HEALING VALIDATION (max 2 iterations)
============================================================

After completing deployment/infrastructure changes, validate:

1. Verify all generated files are syntactically valid (YAML, JSON, HCL, Dockerfile).
2. Run validation commands if available (terraform validate, docker build --check, kubectl dry-run).
3. Verify no secrets, credentials, or sensitive values are hardcoded.
4. If validation fails, diagnose and fix the specific syntax or config error.
5. Repeat up to 2 iterations.

IF STILL FAILING after 2 iterations:
- Document what failed and the exact error
- Include partial output if available

============================================================
OUTPUT
============================================================

```
## Monitoring Setup Complete

### Stack: {Prometheus + Grafana / Datadog / CloudWatch / New Relic}

### Files Created
{list of all generated files with one-line descriptions}

### Metrics Endpoints
- Application: http://localhost:{port}/metrics
- Prometheus: http://localhost:9090
- Grafana: http://localhost:3001 (admin/admin)
- Alertmanager: http://localhost:9093

### Alert Rules
| Alert | Condition | Severity |
|-------|-----------|----------|
| HighErrorRate | >1% for 5m | critical |
| HighLatency | P99 >2s for 5m | warning |
| HighMemory | >512MB for 10m | warning |
| DiskUsageHigh | >80% for 5m | warning |
| ServiceDown | down for 1m | critical |

### Dashboard Panels
{list of dashboard panels with their metric queries}
```

============================================================
NEXT STEPS
============================================================

1. Start monitoring stack: `docker compose -f monitoring/docker-compose.monitoring.yml up -d`
2. Verify metrics are being scraped: check Prometheus targets page at :9090/targets
3. Configure alerting notification channels (Slack, PagerDuty, email) in Alertmanager
4. Add application-specific custom metrics for business KPIs
5. Set up log aggregation if not already configured (Loki, ELK)
6. Review alert thresholds after 1 week of baseline data


============================================================
SELF-EVOLUTION TELEMETRY
============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:
- Look for the project path in `~/.claude/projects/`
- If found, append to `skill-telemetry.md` in that memory directory

Entry format:
```
### /monitoring — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
```

Only log if the memory directory exists. Skip silently if not found.
Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================
DO NOT
============================================================

- Do NOT set alert thresholds too aggressively — avoid alert fatigue
- Do NOT expose Prometheus/Grafana ports publicly without authentication
- Do NOT store Grafana admin passwords in plain text in committed files
- Do NOT use `rate()` on gauges — use `rate()` only on counters and histograms
- Do NOT create alerts without `for` duration — always require sustained condition
- Do NOT use high-cardinality labels (user IDs, request IDs) in Prometheus metrics
- Do NOT scrape more frequently than every 10s without good reason
- Do NOT overwrite existing monitoring configs — extend them
- Do NOT add instrumentation that significantly impacts application performance