Skip to content

Commit 755c149

Browse files
levkklevkk
authored
Document EE (#37)
1 parent 0b67a80 commit 755c149

File tree

8 files changed

+145
-2
lines changed

8 files changed

+145
-2
lines changed

‎docs/enterprise_edition/active_queries.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
icon: material/play-circle
3+
---
4+
# Running queries
5+
6+
PgDog EE provides a real-time view into queries currently executing on PostgreSQL connections. It is accessible in two places:
7+
8+
1. [`SHOW ACTIVE_QUERIES`](#admin-database) admin command
9+
2. [Activity](#dashboard) view in the dashboard
10+
11+
## How it works
12+
13+
When a client sends a query to PgDog, it will first attempt to acquire a connection from the connection pool. Once acquired, it will register the query with the live query view. After the query finishes running, it's removed from the view.
14+
15+
Only queries that are currently executing through PgDog are visible in this view. If your application doesn't connect to PgDog, its queries won't appear here.
16+
17+
### Admin database
18+
19+
You can see which queries are actually running on each instance by connecting to the admin database and running the `SHOW ACTIVE_QUERIES` command:
20+
21+
=== "Command"
22+
```
23+
SHOW ACTIVE_QUERIES;
24+
```
25+
26+
=== "Output"
27+
```
28+
query | protocol | database | user | running_time |
29+
-------------------------------------------------------+----------+----------+-------+--------------+
30+
SELECT * FROM users WHERE id = $1 | extended | pgdog | pgdog | 15 |
31+
SELECT pg_sleep(50) | simple | pgdog | pgdog | 5 |
32+
INSERT INTO users (id, email) VALUES ($1, $2) | extended | pgdog | pgdog | 1 |
33+
```
34+
35+
The following information is available in the running queries view:
36+
37+
| Column | Description |
38+
|-|-|
39+
| `query` | The SQL statement currently executing on a PostgreSQL connection. |
40+
| `protocol` | What version of the query protocol is used. `simple` protocol injects parameters into text, while `extended` is used by prepared statements. |
41+
| `database` | The name of the connection pool database. |
42+
| `user` | The name of the user executing the query. |
43+
| `running_time` | For how long (in ms) has the query been running. |
44+
45+
### Dashboard
46+
47+
If you're running multiple instances of PgDog, active queries from all instances are aggregated and sent to the Dashboard application. They are then made available in the Activity tab, in real-time, with query plans automatically attached for slow queries.
48+
49+
<center>
50+
<img src="/images/ee/activity.png" width="100%" alt="How PgDog works" class="screenshot" />
51+
<i>Real-time view into running queries.</i>
52+
</center>

‎docs/enterprise_edition/index.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
icon: material/office-building
3+
---
4+
5+
# PgDog EE
6+
7+
PgDog **E**nterprise **E**dition is a version of PgDog that contains additional features for at scale monitoring and deployment of sharded (and unsharded) PostgreSQL databases.
8+
9+
Unlike PgDog itself, PgDog EE is closed source and available upon the purchase of a license. It comes with a hosted management dashboard which provides real-time visibility into PgDog's operations.
10+
11+
## Features
12+
13+
| Feature | Description |
14+
|-|-|
15+
| [Running queries](active_queries.md) | Instant view into queries running through PgDog. |
16+
| [Query plans](query_plans.md) | Root cause slow queries in seconds with automatic PostgreSQL query plans. |
17+
| [Real-time metrics](metrics.md) | All PgDog metrics, delivered with second-precision through a dedicated link. |
18+
| Query blocker | Terminate all instances of a slow query with a button click and prevent them from running again. |
19+
20+
## Get a demo
21+
22+
If you'd like a demo of PgDog EE, [get in touch](https://calendly.com/lev-pgdog/30min) with our sales team. PgDog EE comes with a [cloud](https://cloud.pgdog.dev) deployment managed by us, or can be deployed entirely on-prem.

‎docs/enterprise_edition/metrics.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
icon: material/speedometer
3+
---
4+
# Real-time metrics
5+
6+
PgDog EE collects and sends its own metrics to the Dashboard. This provides a real-time view into PgDog internals, without a delay that's typically present in other monitoring solutions.
7+
8+
## How it works
9+
10+
Real-time metrics are available in both Open Source and Enterprise versions of PgDog. The [open source metrics](../features/metrics.md) are accessible via an OpenMetrics endpoint or via the admin database.
11+
12+
In PgDog EE, the same metrics are collected and sent via a dedicated uplink to the Dashboard. This provides an out-of-the-box experience for monitoring deployments, without delays typically introduced by other solutions.
13+
14+
<center>
15+
<img src="/images/ee/metrics.png" width="100%" alt="How PgDog works" class="screenshot" />
16+
<i>Real-time metrics.</i>
17+
</center>
18+
19+
Since metrics are just integers, they can be serialized and sent efficiently. To deliver second-precision metrics, PgDog EE requires less than 1KB/second of bandwidth and basically no CPU or additional memory.
20+
21+
Once the metrics reach the Dashboard, they are pushed down to the web UI via a WebSocket connection. At the same time, per-minute aggregates are computed in the background and stored in a separate Postgres database. This provides a historical view into database performance.

‎docs/enterprise_edition/query_plans.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
icon: material/chart-timeline
3+
---
4+
# Query plans
5+
6+
For any [running query](active_queries.md) exceeding a configurable time threshold, PgDog EE will ask Postgres for a query plan. The query plans are stored in their own view, accessible via two methods:
7+
8+
1. [`SHOW QUERY_PLANS`](#admin-database) admin command
9+
2. [Activity](active_queries.md#dashboard) view in the dashboard
10+
11+
## How it works
12+
13+
When a [running query](active_queries.md) exceeds a configurable threshold, PgDog EE will ask Postgres for its query plan by sending an `EXPLAIN` command via a dedicated connection. For prepared statements, PgDog automatically provides the parameters sent with the statement by the client.
14+
15+
Since `EXPLAIN` itself is very quick, fetching and storing query plans is efficient and doesn't impact database performance. Nonetheless, to avoid planning queries unnecessarily, the plans are stored in an in-memory cache. Old plans are evicted automatically and recomputed.
16+
17+
### Admin database
18+
19+
The query plans are accessible by connecting to the admin database and running the `SHOW QUERY_PLANS` command:
20+
21+
=== "Command"
22+
```
23+
SHOW QUERY_PLANS;
24+
```
25+
=== "Output"
26+
```
27+
query | plan | database | user | age
28+
-------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+-------+---------
29+
select pg_sleep(50); | Result (cost=0.00..0.01 rows=1 width=4) | pgdog | pgdog | 6984139
30+
SELECT abalance FROM pgbench_accounts WHERE aid = $1; | Index Scan using pgbench_accounts_pkey on pgbench_accounts (cost=0.29..8.31 rows=1 width=4) Index Cond: (aid = 96934) | pgdog | pgdog | 7711
31+
(2 rows)
32+
```
33+
34+
The following information is available in this view:
35+
36+
| Column | Description |
37+
|-|-|
38+
| `query` | The query for which the plan is prepared. |
39+
| `plan` | The query plan fetched directly from PostgreSQL. |
40+
| `database` | The name of the connection pool database. |
41+
| `user` | The name of the user running the query. |
42+
| `age` | How long ago the plan was fetched from Postgres (in ms). |
43+
44+
### Dashboard
45+
46+
The query plans are automatically attached to running queries and sent to the Dashboard via a dedicated connection. They can be viewed in real-time in the [Activity](active_queries.md#dashboard) tab.

‎docs/images/ee/activity.png‎

42 KB
Loading

‎docs/images/ee/metrics.png‎

73.9 KB
Loading

‎docs/style.css‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,7 @@ table {
66
.md-header {
77
--md-primary-fg-color: rgb(7, 81, 207);
88
}
9+
10+
.screenshot {
11+
border-radius: 8px;
12+
}

‎tests/test_code_blocks.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@
77
import sys
88
import pglast
99

10-
from regex import sub
11-
from regex.regex import Regex, RegexFlag
1210
mdp = MarkdownIt()
1311

1412
pattern = re.compile(

0 commit comments

Comments
 (0)