Skip to content

Commit eb2913f

Browse files
levkklevkk
committed
fix: metrics docs
1 parent bb7391c commit eb2913f

File tree

3 files changed

+58
-35
lines changed

3 files changed

+58
-35
lines changed

‎docs/enterprise_edition/control_plane/self-hosting.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,11 @@ The control plane has two dependencies:
1717
1. A PostgreSQL database used to store historical metrics, query statistics, users and other metadata
1818
2. A Redis database, used for synchronization and real-time metrics
1919

20-
If you're using our [Helm chart](#kubernetes), both are provided automatically.
20+
If you're using our [Helm chart](#kubernetes), Redis is deployed automatically, while the PostgreSQL database has to be created manually.
2121

2222
### Kubernetes
2323

24-
If you're running PgDog in Kubernetes using our [Helm chart](../../installation.md#kubernetes), you can deploy the control plane into the same cluster using our Enterprise Helm chart:
24+
If you're already running PgDog in Kubernetes using our [Helm chart](../../installation.md#kubernetes), you can deploy the control plane into the same cluster using our Enterprise Helm chart:
2525

2626
```
2727
helm repo add pgdogdev-ee https://helm-ee.pgdog.dev
@@ -49,6 +49,9 @@ env:
4949
5050
### Configuration
5151
52+
!!! note "Helm chart"
53+
If you're using the [Helm chart](#kubernetes), all variables except `DATABASE_URL` are generated from settings in `values.yaml` and don't need to be configured manually.
54+
5255
The control plane is configured via environment variables. The following variables are required for it to work correctly:
5356

5457
| Environment variable | Description | Example |
@@ -58,8 +61,7 @@ The control plane is configured via environment variables. The following variabl
5861
| `REDIS_URL` | URL pointing to the Redis database used for synchronization. | `redis://127.0.0.1/0` |
5962
| `FRONTEND_URL` | The URL where the frontend application is hosted. This defaults to `ingress.host` if you're using the Helm chart. | `http://pgdog.internal` |
6063

61-
!!! note "Helm chart"
62-
If you're using the [Helm chart](#kubernetes), all variables except `DATABASE_URL` are generated from settings in `values.yaml` and don't need to be configured manually.
64+
6365

6466
#### Session key
6567

‎docs/enterprise_edition/metrics.md‎

Lines changed: 32 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -40,68 +40,69 @@ Dashboard metrics are distinct from the [OpenMetrics endpoint](../features/metri
4040

4141
| Metric | Description |
4242
|--------|-------------|
43-
| Clients | Total number of clients connected to PgDog. |
43+
| Clients | Total number of connected clients. |
4444
| Server Connections | Total server connections open across all pools. |
45-
| Connection Rate (cps) | New server connections established from PgDog to PostgreSQL per second. |
46-
| Waiting | Clients currently queued waiting for a server connection. |
47-
| 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. |
48-
| Idle Connections | Server connections open and available for use. |
49-
| 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. |
50-
| Checked Out | Server connections currently serving an active client request. |
45+
| Connection Rate (cps) | Average number of connections established to servers per second. |
46+
| Waiting | Clients waiting for a connection from a pool. |
47+
| Max Wait (ms) | How long the first (oldest) client in the queue has waited, in milliseconds. |
48+
| Idle Connections | Servers available for clients to use. |
49+
| Idle in Transaction Connections | Servers currently idle in transaction. |
50+
| Checked Out | Servers currently serving client requests. |
5151
| Instances | Number of PgDog instances currently connected to the control plane. |
5252

5353
### Errors
5454

5555
| Metric | Description |
5656
|--------|-------------|
57-
| Errors | Client-facing errors per second across all pools. |
58-
| Server Errors | Errors reported by upstream PostgreSQL servers per second. |
57+
| Errors | Errors that connections in the pool have experienced. |
58+
| Server Errors | Errors returned by server connections. |
5959

6060
### Query throughput
6161

6262
| Metric | Description |
6363
|--------|-------------|
64-
| Queries | Queries executed through PgDog per second. |
65-
| Transactions | Transactions completed per second. |
66-
| Transaction Rate (tps) | Rolling average transactions per second. |
67-
| Query Rate (qps) | Rolling average queries per second. |
68-
| Blocked Queries | Queries blocked by lock contention per second. |
64+
| Queries | Total number of executed queries. |
65+
| Transactions | Total number of executed transactions. |
66+
| Transaction Rate (tps) | Average number of executed transactions per statistics period. |
67+
| Query Rate (qps) | Average number of executed queries per statistics period. |
68+
| Blocked Queries | Queries blocked by lock contention. |
6969

7070
### Timing and latency
7171

7272
| Metric | Description |
7373
|--------|-------------|
74-
| Query Time (ms) | Total query execution time per second. Does not include connection wait. |
75-
| Transaction Time (ms) | Total transaction execution time per second. Includes idle-in-transaction time; does not include connection wait. |
76-
| Idle in Transaction Time (ms) | Time per second spent idle inside open transactions. Elevated values indicate clients holding transactions open without executing queries. |
77-
| 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. |
78-
| Query Response Time (ms) | Full client-observed query latency per second, including connection wait time. |
79-
| Transaction Response Time (ms) | Full client-observed transaction latency per second, including connection wait time. |
74+
| Query Time (ms) | Total time spent executing queries. |
75+
| Transaction Time (ms) | Total time spent executing transactions. |
76+
| Idle in Transaction Time (ms) | Total time spent idling inside transactions. |
77+
| Wait Time (ms) | Total time clients spent waiting for a server connection. |
78+
| Query Response Time (ms) | Total client-observed query latency, including connection wait time. |
79+
| Transaction Response Time (ms) | Total client-observed transaction latency, including connection wait time. |
8080

8181
!!! note "Max Wait vs Wait Time"
82-
**Max Wait** captures the worst single waiter at one instant — it drops to zero the moment that client is served.
83-
**Wait Time** measures total queuing burden per second across all clients — it stays elevated when many clients are waiting briefly.
82+
**Max Wait** captures the worst single waiter at one instant. It drops to zero the moment that client is served.
83+
84+
**Wait Time** measures total queuing burden across all clients. It stays elevated when many clients are waiting briefly.
8485
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.
8586

8687
### Network throughput
8788

8889
| Metric | Description |
8990
|--------|-------------|
90-
| Bytes Received (MB) | Megabytes received from PostgreSQL servers per second. |
91-
| Bytes Sent (MB) | Megabytes sent to PostgreSQL servers per second. |
91+
| Bytes Received (MB) | Total number of bytes received. |
92+
| Bytes Sent (MB) | Total number of bytes sent. |
9293

9394
### Memory and caching
9495

9596
| Metric | Description |
9697
|--------|-------------|
97-
| Prepared Statements | Number of prepared statements in the PgDog global cache. |
98-
| Prepared Statements Memory (MB) | Memory consumed by the prepared statements cache. |
99-
| Query Cache Size | Number of parsed queries stored in the query cache. |
100-
| Query Cache Hits | AST query cache hits per second. |
101-
| Query Cache Misses | AST query cache misses per second. |
98+
| Prepared Statements | Number of prepared statements in the cache. |
99+
| Prepared Statements Memory (MB) | Number of bytes used for the prepared statements cache. |
100+
| Query Cache Size | Number of queries in the cache. |
101+
| Query Cache Hits | Queries already present in the query cache. |
102+
| Query Cache Misses | New queries added to the query cache. |
102103
| Query Cache Hit Rate (%) | Percentage of queries served from the query cache. |
103-
| Direct Shard Queries | Queries routed to a single shard per second. |
104-
| Cross-Shard Queries | Queries broadcast to multiple shards per second. |
104+
| Direct Shard Queries | Queries sent directly to a single shard. |
105+
| Cross-Shard Queries | Queries sent to multiple or all shards. |
105106
| Direct Shard Hit Rate (%) | Percentage of queries that avoided a cross-shard fanout. |
106107

107108
### Query stats

‎docs/features/metrics.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,3 +106,23 @@ The following metrics are exported via the OpenMetrics endpoint:
106106
| `query_cache_size` | Number of queries in the cache. | `gauge` |
107107
| `prepared_statements` | Number of prepared statements in the cache. | `gauge` |
108108
| `prepared_statements_memory_used` | Number of bytes used for the prepared statements cache. | `gauge` |
109+
| `prepared_statements_limit` | Maximum number of prepared statements that can be cached. | `gauge` |
110+
| `max_connections` | Maximum number of allowed server connections. | `gauge` |
111+
| `total_connect_count` | Total number of connections established to servers. | `counter` |
112+
| `avg_connect_count` | Average number of connections established to servers. | `gauge` |
113+
| `total_connect_time` | Total time spent connecting to servers. | `counter` |
114+
| `avg_connect_time` | Average time spent connecting to servers. | `gauge` |
115+
| `total_idle_xact_time` | Total time spent idling inside transactions. | `counter` |
116+
| `avg_idle_xact_time` | Average time spent idling inside transactions. | `gauge` |
117+
| `total_reads` | Total number of read transactions. | `counter` |
118+
| `avg_reads` | Average number of read transactions per statistics period. | `gauge` |
119+
| `total_writes` | Total number of write transactions. | `counter` |
120+
| `avg_writes` | Average number of write transactions per statistics period. | `gauge` |
121+
| `total_rollbacks` | Total number of abandoned transactions that had to be rolled back automatically. | `counter` |
122+
| `avg_rollbacks` | Average number of abandoned transactions that had to be rolled back automatically. | `gauge` |
123+
| `total_server_errors` | Total number of errors returned by server connections. | `counter` |
124+
| `avg_server_errors` | Average number of errors returned by server connections. | `gauge` |
125+
| `total_cleaned` | Total number of times server connections were cleaned from client parameters. | `counter` |
126+
| `avg_cleaned` | Average number of times server connections were cleaned from client parameters. | `gauge` |
127+
| `query_cache_limit` | Maximum number of queries that can be stored in the cache. | `gauge` |
128+
| `query_cache_parse_time` | Time spent parsing queries due to cache misses. | `counter` |

0 commit comments

Comments
 (0)