Monitoring with Prometheus and Grafana

Monitoring with Prometheus and Grafana

CCAM exposes Prometheus metrics for service health and workload shape. Monitoring should tell you whether collection is trustworthy before users discover missing or stale history.

Fast start

npm run monitoring:up
npm run monitoring:verify

For the complete Compose topology, npm run docker:full:up provisions the dashboard, Prometheus, Grafana, Nginx, and MCP services. Default host bindings remain on loopback.

Protect metrics

GET /api/metrics is operationally sensitive and supports dashboard bearer authentication. Keep it on a private network and configure Prometheus with the dashboard token. The supplied full-stack edge policy does not publish it.

Monitor four layers

1. Availability — health probe, process uptime, restart count.
2. Ingestion — event growth, session activity, remote-source health.
3. Realtime delivery — connected clients and proxy/WebSocket health.
4. Capacity — process memory, database/volume growth, backup age, scrape health.

Starter PromQL

sum(ccam_sessions)
ccam_events_total
rate(ccam_tokens_total[5m])

Check the current metric names in the metrics API reference before encoding long-lived alerts.

Alert on symptoms that need ownership

Good service alerts include: dashboard unreachable, repeated restart, scrape failure, database volume nearing capacity, remote source in sustained error, or no ingestion during a known active period. Avoid alerting on every agent error; many are workload outcomes rather than platform incidents.

Dashboard interpretation

The provisioned Grafana dashboards cover overview, platform, sessions/agents, and tokens/events. Use them to identify a time window and affected source, then investigate the corresponding CCAM sessions. Grafana aggregates; the session timeline provides causal detail.

Operational verification

After deploying or changing auth:

• Prometheus target is up and authenticated.
• Grafana datasource is healthy.
• counters advance during a controlled test session.
• no token appears in logs or dashboard variables visible to viewers.
• alert routes reach an owned receiver.

Detailed setup lives in monitoring/README.md.