From 3206f2aa3d15f2b13426f51c1ad13e69fb26fbdc Mon Sep 17 00:00:00 2001
From: meskill <8974488+meskill@users.noreply.github.com>
Date: Mon, 23 Mar 2026 22:28:10 +0000
Subject: [PATCH] feat: add EE metrics description

---
 docs/enterprise_edition/metrics.md | 79 ++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/docs/enterprise_edition/metrics.md b/docs/enterprise_edition/metrics.md
index ac02453..62a0393 100644
--- a/docs/enterprise_edition/metrics.md
+++ b/docs/enterprise_edition/metrics.md
@@ -31,3 +31,82 @@ Once the metrics reach the control plane, they are pushed down to the web dashbo
 <center>
   <img src="/images/ee/metrics.png" width="100%" alt="PgDog Real-time Metrics" class="screenshot" />
 </center>
+
+## Available dashboard metrics
+
+Dashboard metrics are distinct from the [OpenMetrics endpoint](../features/metrics.md). They use millisecond units throughout and are collected at specified intervals.
+
+### Connection pool
+
+| Metric | Description |
+|--------|-------------|
+| Clients | Total number of clients connected to PgDog. |
+| Server Connections | Total server connections open across all pools. |
+| Connection Rate (cps) | New server connections established from PgDog to PostgreSQL per second. |
+| Waiting | Clients currently queued waiting for a server connection. |
+| Max Wait (ms) | Age of the oldest client currently waiting for a connection. Resets to zero when the queue drains. Useful for spotting individual outlier waits. |
+| Idle Connections | Server connections open and available for use. |
+| Idle in Transaction Connections | Server connections currently idle inside an open transaction. Historical chart data for this metric is not currently tracked and will show zero. |
+| Checked Out | Server connections currently serving an active client request. |
+| Instances | Number of PgDog instances currently connected to the control plane. |
+
+### Errors
+
+| Metric | Description |
+|--------|-------------|
+| Errors | Client-facing errors per second across all pools. |
+| Server Errors | Errors reported by upstream PostgreSQL servers per second. |
+
+### Query throughput
+
+| Metric | Description |
+|--------|-------------|
+| Queries | Queries executed through PgDog per second. |
+| Transactions | Transactions completed per second. |
+| Transaction Rate (tps) | Rolling average transactions per second. |
+| Query Rate (qps) | Rolling average queries per second. |
+| Blocked Queries | Queries blocked by lock contention per second. |
+
+### Timing and latency
+
+| Metric | Description |
+|--------|-------------|
+| Query Time (ms) | Total query execution time per second. Does not include connection wait. |
+| Transaction Time (ms) | Total transaction execution time per second. Includes idle-in-transaction time; does not include connection wait. |
+| Idle in Transaction Time (ms) | Time per second spent idle inside open transactions. Elevated values indicate clients holding transactions open without executing queries. |
+| Wait Time (ms) | Total time all clients spent waiting for a server connection per second. Unlike Max Wait, this stays elevated when many clients are waiting briefly. |
+| Query Response Time (ms) | Full client-observed query latency per second, including connection wait time. |
+| Transaction Response Time (ms) | Full client-observed transaction latency per second, including connection wait time. |
+
+!!! note "Max Wait vs Wait Time"
+    **Max Wait** captures the worst single waiter at one instant — it drops to zero the moment that client is served.
+    **Wait Time** measures total queuing burden per second across all clients — it stays elevated when many clients are waiting briefly.
+    Use both together: high Max Wait with low Wait Time points to a single slow client; high Wait Time with low Max Wait indicates widespread shallow queuing.
+
+### Network throughput
+
+| Metric | Description |
+|--------|-------------|
+| Bytes Received (MB) | Megabytes received from PostgreSQL servers per second. |
+| Bytes Sent (MB) | Megabytes sent to PostgreSQL servers per second. |
+
+### Memory and caching
+
+| Metric | Description |
+|--------|-------------|
+| Prepared Statements | Number of prepared statements in the PgDog global cache. |
+| Prepared Statements Memory (MB) | Memory consumed by the prepared statements cache. |
+| Query Cache Size | Number of parsed queries stored in the query cache. |
+| Query Cache Hits | AST query cache hits per second. |
+| Query Cache Misses | AST query cache misses per second. |
+| Query Cache Hit Rate (%) | Percentage of queries served from the query cache. |
+| Direct Shard Queries | Queries routed to a single shard per second. |
+| Cross-Shard Queries | Queries broadcast to multiple shards per second. |
+| Direct Shard Hit Rate (%) | Percentage of queries that avoided a cross-shard fanout. |
+
+### Query stats
+
+| Metric | Description |
+|--------|-------------|
+| Query Stats Tracked Queries | Number of unique query fingerprints currently tracked. |
+| Query Stats Memory (MB) | Memory consumed by the query stats store. |