diff --git a/docs/enterprise_edition/active_queries.md b/docs/enterprise_edition/active_queries.md new file mode 100644 index 0000000..65bd964 --- /dev/null +++ b/docs/enterprise_edition/active_queries.md @@ -0,0 +1,52 @@ +--- +icon: material/play-circle +--- +# Running queries + +PgDog EE provides a real-time view into queries currently executing on PostgreSQL connections. It is accessible in two places: + +1. [`SHOW ACTIVE_QUERIES`](#admin-database) admin command +2. [Activity](#dashboard) view in the dashboard + +## How it works + +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. + +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. + +### Admin database + +You can see which queries are actually running on each instance by connecting to the admin database and running the `SHOW ACTIVE_QUERIES` command: + +=== "Command" + ``` + SHOW ACTIVE_QUERIES; + ``` + +=== "Output" + ``` + query | protocol | database | user | running_time | + -------------------------------------------------------+----------+----------+-------+--------------+ + SELECT * FROM users WHERE id = $1 | extended | pgdog | pgdog | 15 | + SELECT pg_sleep(50) | simple | pgdog | pgdog | 5 | + INSERT INTO users (id, email) VALUES ($1, $2) | extended | pgdog | pgdog | 1 | + ``` + +The following information is available in the running queries view: + +| Column | Description | +|-|-| +| `query` | The SQL statement currently executing on a PostgreSQL connection. | +| `protocol` | What version of the query protocol is used. `simple` protocol injects parameters into text, while `extended` is used by prepared statements. | +| `database` | The name of the connection pool database. | +| `user` | The name of the user executing the query. | +| `running_time` | For how long (in ms) has the query been running. | + +### Dashboard + +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. + +
+ How PgDog works + Real-time view into running queries. +
diff --git a/docs/enterprise_edition/index.md b/docs/enterprise_edition/index.md new file mode 100644 index 0000000..94d778d --- /dev/null +++ b/docs/enterprise_edition/index.md @@ -0,0 +1,22 @@ +--- +icon: material/office-building +--- + +# PgDog EE + +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. + +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. + +## Features + +| Feature | Description | +|-|-| +| [Running queries](active_queries.md) | Instant view into queries running through PgDog. | +| [Query plans](query_plans.md) | Root cause slow queries in seconds with automatic PostgreSQL query plans. | +| [Real-time metrics](metrics.md) | All PgDog metrics, delivered with second-precision through a dedicated link. | +| Query blocker | Terminate all instances of a slow query with a button click and prevent them from running again. | + +## Get a demo + +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. diff --git a/docs/enterprise_edition/metrics.md b/docs/enterprise_edition/metrics.md new file mode 100644 index 0000000..4e84981 --- /dev/null +++ b/docs/enterprise_edition/metrics.md @@ -0,0 +1,21 @@ +--- +icon: material/speedometer +--- +# Real-time metrics + +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. + +## How it works + +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. + +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. + +
+ How PgDog works + Real-time metrics. +
+ +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. + +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. diff --git a/docs/enterprise_edition/query_plans.md b/docs/enterprise_edition/query_plans.md new file mode 100644 index 0000000..8273dfc --- /dev/null +++ b/docs/enterprise_edition/query_plans.md @@ -0,0 +1,46 @@ +--- +icon: material/chart-timeline +--- +# Query plans + +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: + +1. [`SHOW QUERY_PLANS`](#admin-database) admin command +2. [Activity](active_queries.md#dashboard) view in the dashboard + +## How it works + +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. + +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. + +### Admin database + +The query plans are accessible by connecting to the admin database and running the `SHOW QUERY_PLANS` command: + +=== "Command" + ``` + SHOW QUERY_PLANS; + ``` +=== "Output" + ``` + query | plan | database | user | age + -------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+----------+-------+--------- + select pg_sleep(50); | Result (cost=0.00..0.01 rows=1 width=4) | pgdog | pgdog | 6984139 + 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 + (2 rows) + ``` + +The following information is available in this view: + +| Column | Description | +|-|-| +| `query` | The query for which the plan is prepared. | +| `plan` | The query plan fetched directly from PostgreSQL. | +| `database` | The name of the connection pool database. | +| `user` | The name of the user running the query. | +| `age` | How long ago the plan was fetched from Postgres (in ms). | + +### Dashboard + +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. diff --git a/docs/images/ee/activity.png b/docs/images/ee/activity.png new file mode 100644 index 0000000..efb0427 Binary files /dev/null and b/docs/images/ee/activity.png differ diff --git a/docs/images/ee/metrics.png b/docs/images/ee/metrics.png new file mode 100644 index 0000000..2542bb8 Binary files /dev/null and b/docs/images/ee/metrics.png differ diff --git a/docs/style.css b/docs/style.css index 57a5253..b739812 100644 --- a/docs/style.css +++ b/docs/style.css @@ -6,3 +6,7 @@ table { .md-header { --md-primary-fg-color: rgb(7, 81, 207); } + +.screenshot { + border-radius: 8px; +} diff --git a/tests/test_code_blocks.py b/tests/test_code_blocks.py index 2fb56d4..a2c7912 100644 --- a/tests/test_code_blocks.py +++ b/tests/test_code_blocks.py @@ -7,8 +7,6 @@ import sys import pglast -from regex import sub -from regex.regex import Regex, RegexFlag mdp = MarkdownIt() pattern = re.compile(