feat: aws cloudwatch metrics source

examples/metrics-source/.env.example

@@ -27,6 +27,16 @@ AGENT_AI_ENABLE=false
 AGENT_AI_API_KEY=
 AGENT_AI_MODEL=gpt-4o-mini
 
+# --- CloudWatch Metrics variant (docker-compose.cloudwatch.yml) --------------
+# Only needed when running the CloudWatch source. Standard AWS SDK credential
+# chain — AWS_REGION is REQUIRED; leave the key/secret empty to use an EC2/ECS
+# instance role instead. Do NOT wrap any value in quotes (compose forwards them
+# literally, and a quoted region is an invalid region).
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_SESSION_TOKEN=
+
 # --- Optional: notifications -------------------------------------------------
 SLACK_ENABLE=false
 SLACK_TOKEN=

examples/metrics-source/README.md

@@ -380,17 +380,44 @@ signal per matching trace; `query_traces` (also auto-wired, no tools.yaml) lets
 the AI pull redacted span summaries during investigation. Tempo's API is on
 `:3200`, OTLP on `:4318`.
 
+## Optional: CloudWatch Metrics (AWS)
+
+To watch a **real AWS account** instead of the local Prometheus stack, use the
+standalone CloudWatch variant. CloudWatch reads from AWS, so there is no local
+metric stack — this compose file runs just Redis and the enterprise agent:
+
+```bash
+cp .env.example .env      # paste LICENSE_KEY, then set AWS_REGION + credentials
+docker compose -f docker-compose.cloudwatch.yml up -d
+```
+
+The `cloudwatch_metrics` source needs only an **AWS region** (auth comes from the
+standard AWS SDK credential chain) and read-only CloudWatch access
+(`cloudwatch:ListMetrics` + `cloudwatch:GetMetricData`). It discovers every
+`AWS/*` metric it can attribute to a service, learns each one's baseline, and —
+in `detect` mode — pages on a real, sustained deviation. Unlike the Prometheus
+demo there is no synthetic spike: it watches your real AWS metrics. Full
+walkthrough: [CloudWatch Metrics guide](../../src/enterprise/metrics/cloudwatch-metrics.md).
+
+Tear down:
+
+```bash
+docker compose -f docker-compose.cloudwatch.yml down -v
+```
+
 ## Layout
 
 ```
 metrics-source/
 ├── docker-compose.yml              # enterprise versus + redis + prometheus + pushgateway
 ├── docker-compose.traces.yml       # optional overlay: + tempo
+├── docker-compose.cloudwatch.yml   # standalone: CloudWatch (AWS) — redis + versus, no local stack
 ├── .env.example                    # copy to .env; holds LICENSE_KEY (gitignored)
 ├── config/
 │   ├── config.yaml                 # mode=detect, new_service_grace=0
 │   ├── agent_sources.yaml          # enterprise prometheus source (options: schema)
-│   └── agent_sources.traces.yaml   # + traces source (overlay only)
+│   ├── agent_sources.traces.yaml   # + traces source (traces overlay only)
+│   └── agent_sources.cloudwatch.yaml # CloudWatch metrics source (cloudwatch compose only)
 │   #  NOTE: no tools.yaml — query_metrics/query_traces are auto-wired
 ├── prometheus/
 │   └── prometheus.yml              # scrapes the pushgateway (honor_labels: true)
@@ -407,6 +434,8 @@ python3 scripts/generate_fake_metrics.py --clear   # drop the pushed series
 docker compose down -v
 # or, if you ran the traces overlay:
 docker compose -f docker-compose.yml -f docker-compose.traces.yml down -v
+# or, if you ran the CloudWatch variant:
+docker compose -f docker-compose.cloudwatch.yml down -v
 ```
 
 ## Reference

examples/metrics-source/config/agent_sources.cloudwatch.yaml

@@ -0,0 +1,42 @@
+# Enterprise `cloudwatch_metrics` DATA SOURCE for the metrics-source example.
+#
+# CloudWatch twin of agent_sources.yaml. The ONLY required field is `region`;
+# authentication comes from the standard AWS SDK credential chain (the AWS_*
+# env vars docker-compose.cloudwatch.yml forwards from your .env). There are NO
+# static keys in this file.
+#
+# Enterprise-only: needs a LICENSE_KEY with the `intelligence` entitlement. On an
+# OSS build the `cloudwatch_metrics` type is unavailable and the source fails
+# closed with "requires Versus Enterprise".
+sources:
+  - name: demo-cloudwatch
+    type: cloudwatch_metrics
+    enable: true
+    options:
+      region: ${AWS_REGION}          # REQUIRED — the only required field
+      namespaces:
+        - AWS/*                       # discover every AWS-service namespace
+
+      # ---------------------------------------------------------------------
+      # OPTIONAL knobs — every one defaults when omitted. Uncomment to tune
+      # scope or cost; the documented path is region-only.
+      #
+      # poll_interval: 60s            # sampling cadence (default 60s)
+      # query_delay: 120s             # offset for CloudWatch ingestion lag —
+      #                               # queries a window ending at now-query_delay
+      # period: 60                    # GetMetricData period, seconds (default 60)
+      #
+      # namespaces:                   # narrow discovery to bound cost on large
+      #   - AWS/ApplicationELB        # accounts. Custom (non-AWS/) namespaces are
+      #   - AWS/RDS                   # EXCLUDED unless you list them here.
+      #   - AWS/SQS
+      #
+      # default_statistic: Average    # statistic sampled for every metric
+      # statistic_overrides:          # per-namespace override (extended stats OK)
+      #   AWS/ApplicationELB: p99     #   latency — track the slow tail
+      #   AWS/SQS: Sum                #   queue depth — total, not average
+      #
+      # max_services: 200             # discovery cap: distinct services
+      # max_signals: 2000             # discovery cap: total signals
+      # discovery_interval: 1h        # how often the watch-set is refreshed
+      # ---------------------------------------------------------------------

examples/metrics-source/docker-compose.cloudwatch.yml

@@ -0,0 +1,100 @@
+# Standalone CloudWatch Metrics variant of the metrics-source example.
+#
+# CloudWatch reads from a real AWS account, so — unlike the Prometheus base —
+# there is NO local metric stack to run. This file is COMPLETE on its own
+# (Redis + the enterprise agent); run it directly, not as an overlay:
+#
+#   cp .env.example .env      # paste LICENSE_KEY + set AWS_REGION and creds
+#   docker compose -f docker-compose.cloudwatch.yml up -d
+#
+# It reuses the shared config/config.yaml (file storage) and swaps in the
+# CloudWatch source variant (config/agent_sources.cloudwatch.yaml).
+#
+# Enterprise-only: the versus image + a LICENSE_KEY carrying the `intelligence`
+# entitlement are REQUIRED. On the OSS image the `cloudwatch_metrics` type is
+# unavailable and the source fails closed.
+name: versus-cloudwatch-metrics
+
+services:
+  redis:
+    image: redis:7-alpine
+    container_name: versus-cw-metrics-redis
+    command:
+      - redis-server
+      - --requirepass
+      - ${REDIS_PASSWORD:-versus}
+    volumes:
+      - redis-data:/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD:-versus}", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  # The ENTERPRISE image. The CloudWatch metric DATA SOURCE is enterprise-only,
+  # so this MUST run the enterprise image AND supply a LICENSE_KEY carrying the
+  # `intelligence` entitlement. Without it the source logs "requires Versus
+  # Enterprise" on the next tick.
+  versus:
+    image: ${VERSUS_ENTERPRISE_IMAGE:-ghcr.io/versuscontrol/versus-enterprise}
+    container_name: versus-cw-metrics-app
+    depends_on:
+      redis:
+        condition: service_healthy
+    ports:
+      - "3000:3000"
+    environment:
+      # --- Enterprise license (REQUIRED; MUST carry `intelligence`) --------
+      # Offline-verified Ed25519 JWT. Supplied from your local .env — NEVER
+      # commit a real key.
+      LICENSE_KEY: ${LICENSE_KEY:-}
+      # --- Data-plane auth: built-in default admin (session) ---------------
+      # The admin UI is authenticated by a LIVE SESSION — the built-in default
+      # admin (username `admin`; password printed ONCE in the logs on first
+      # boot) or SSO. The shim below drops the Secure cookie attribute so that
+      # session cookie survives plain HTTP on localhost. Dev-only — NEVER set
+      # behind TLS in production.
+      VERSUS_ENTERPRISE_COOKIE_INSECURE: "1"
+      # --- Shared / OSS config ---------------------------------------------
+      STORAGE_TYPE: file
+      REDIS_HOST: redis
+      REDIS_PORT: "6379"
+      REDIS_PASSWORD: ${REDIS_PASSWORD:-versus}
+      # Local Redis is plaintext — dial without TLS (matches the run harness).
+      REDIS_TLS: "false"
+      SLACK_ENABLE: ${SLACK_ENABLE:-false}
+      SLACK_TOKEN: ${SLACK_TOKEN:-}
+      SLACK_CHANNEL_ID: ${SLACK_CHANNEL_ID:-}
+      TELEGRAM_ENABLE: ${TELEGRAM_ENABLE:-false}
+      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:-}
+      TELEGRAM_CHAT_ID: ${TELEGRAM_CHAT_ID:-}
+      AGENT_ENABLE: ${AGENT_ENABLE:-true}
+      # CloudWatch is a STANDING baseline source — start in `training` to learn
+      # each signal's normal, then move to `shadow` and `detect` (see the guide).
+      AGENT_MODE: ${AGENT_MODE:-training}
+      AGENT_AI_ENABLE: ${AGENT_AI_ENABLE:-false}
+      AGENT_AI_API_KEY: ${AGENT_AI_API_KEY:-}
+      AGENT_AI_MODEL: ${AGENT_AI_MODEL:-gpt-4o-mini}
+      # --- AWS auth: STANDARD SDK chain. AWS_REGION is REQUIRED. -----------
+      # Do NOT quote values in .env — compose forwards them literally, so a
+      # quoted region ("us-east-1") becomes an invalid region and every AWS
+      # call fails. Leave the key/secret empty to use an instance/task role.
+      AWS_REGION: ${AWS_REGION:-}
+      AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID:-}
+      AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY:-}
+      AWS_SESSION_TOKEN: ${AWS_SESSION_TOKEN:-}
+    volumes:
+      - ./config:/app/config:ro
+      - ./config/agent_sources.cloudwatch.yaml:/app/config/agent_sources.yaml:ro
+      - versus-data:/app/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3000/healthz"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+
+volumes:
+  redis-data:
+  versus-data:

src/_sidebar.md

@@ -15,7 +15,8 @@
     - [CloudWatch Logs](/agent/data-sources/cloudwatch-logs)
     - [Graylog](/agent/data-sources/graylog)
     - [Splunk](/agent/data-sources/splunk)
-    - [Prometheus / Metrics](/agent/data-sources/prometheus)
+    - [Prometheus](/agent/data-sources/prometheus)
+    - [CloudWatch Metrics](/agent/data-sources/cloudwatch-metrics)
     - [Traces / Tempo](/agent/data-sources/traces)
   - [Notification Channels](/agent/channels)
     - [Slack](/agent/channels/slack)
@@ -46,7 +47,10 @@
     - [Docker Compose](/enterprise/ha/docker)
     - [Kubernetes](/enterprise/ha/kubernetes)
     - [Helm](/enterprise/ha/helm)
-  - [Metrics (Prometheus)](/enterprise/metrics)
+  - [Metrics](/enterprise/metrics)
+    - [Overview](/enterprise/metrics/overview)
+    - [Prometheus](/enterprise/metrics/prometheus)
+    - [CloudWatch Metrics](/enterprise/metrics/cloudwatch-metrics)
   - [Traces](/enterprise/traces)
   - [SLI/SLO auto-define](/enterprise/slo)