Couchbase Observability

Couchbase Observability

A skill for monitoring and alerting on Couchbase clusters in production — metrics, thresholds, Prometheus integration, Grafana dashboards, log aggregation, and health check patterns.

Distinct from:

• couchbase-mcp — calling admin_stats_* tools to read current state
• couchbase-security-hardening — audit log configuration and shipping

When this skill applies

• "How do I monitor Couchbase?"
• "What metrics should I alert on?"
• "How do I integrate Couchbase with Prometheus / Grafana?"
• "What's a good alert threshold for memory / disk / replication lag?"
• "How do I know if a node is healthy?"
• "How do I aggregate Couchbase logs?"
• "How do I set up dashboards for Couchbase?"
• "What does the cache miss ratio tell me?"
• "How do I detect query performance degradation?"

Pick the right reference

| Question | Read | |---|---| | "What metrics matter and what do they mean?" | references/key-metrics.md | | "Prometheus / Grafana setup — scraping, dashboards, recording rules" | references/prometheus-grafana.md | | "Alert thresholds — what values should trigger pages vs warnings?" | references/alert-thresholds.md | | "Log aggregation — shipping cluster logs to ELK / Splunk / Datadog" | references/log-aggregation.md |

Three core principles

Principle 1 — Alert on symptoms, not causes. "Disk usage > 80%" is a symptom. "Compaction not keeping up" is a cause. Alert on the symptom (disk), investigate causes during the incident. Symptom-based alerts have fewer false positives and fewer missed incidents.

Principle 2 — Baseline before you threshold. Couchbase metrics vary enormously by workload. A cache miss ratio of 20% is catastrophic for a key-value workload and perfectly acceptable for an analytics workload. Baseline your metrics for one week before setting alert thresholds.

Principle 3 — Every node matters. Couchbase is a distributed system. A single node with high memory pressure, disk usage, or replication lag can degrade the whole cluster. Aggregate cluster-level metrics for dashboards, but alert per-node on resource pressure.

Quick tool map

| Task | Tool | |---|---| | Cluster-level stats (ops/sec, memory, disk) | admin_stats_cluster | | Per-node stats | admin_stats_nodes | | Bucket-level stats | admin_stats_bucket | | Index stats (GSI) | admin_stats_indexes | | XDCR replication stats | admin_stats_xdcr | | Query service stats | admin_stats_query | | FTS / Search stats | admin_stats_fts | | Eventing stats | admin_stats_eventing | | Analytics stats | admin_stats_analytics | | System events (cluster history) | admin_cluster_get_system_events | | Prometheus scrape targets | admin_stats_prometheus_targets | | Cluster logs | admin_cluster_get_logs |

Related skills

• couchbase-mcp — the admin_stats_* tools that expose the raw metric data
• couchbase-security-hardening — audit log shipping (separate from operational log shipping)
• couchbase-xdcr — XDCR-specific metric interpretation (changes_left, docs_failed_cr_source)
• couchbase-eventing — Eventing-specific stats (dcp_backlog, failed_count, timeout_count)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: celticht32
• Source: celticht32/Couchbase-Skills-for-Claude.ai
• License: MIT

Install and usage instructions live in the source repository linked above.