external
/
pg_stat_monitor
mirror of https://github.com/percona/pg_stat_monitor.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PG-473 Drop docs and disable build on GH pages 

With the documentation moved to a separate repo, remove the docs from this repository to avoid confusion where to contribute to docs. Also, removing a GH action and unpublishing the GH pages site with the docs being built on Render. Updated README and Contributing guide with the new docs repo.

deleted:    .github/workflows/doc-build.yml
	modified:   README.md
	deleted:    docs/COMPARISON.md
	deleted:    docs/REFERENCE.md
	deleted:    docs/USER_GUIDE.md
	deleted:    docs/_images/percona-favicon.ico
	deleted:    docs/_images/percona-logo.svg
	deleted:    docs/css/percona.css
	deleted:    docs/css/toctree.css
	deleted:    docs/index.md
	deleted:    docs/js/version-select.js
	deleted:    docs/overrides/404.html
	deleted:    docs/setup.md
	deleted:    requirements-doc.txt
pull/288/head
Anastasia Alexadrova 2022-08-03 17:52:57 +02:00
parent cd61f9fa27
commit d499a23bdb
16 changed files with 10 additions and 1397 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
.github/workflows/doc-build.yml vendored
View File

@ -1,50 +0,0 @@
name: Build pg_stat_monitor docs
on:
push:
branches:
- REL_1_STABLE
jobs:
build:
name: Deploy docs
runs-on: ubuntu-latest
steps:
#Pull the latest changes
- name: Chekout code
uses: percona-platform/checkout@v2
with:
fetch-depth: 0
#Prepare the env
- name: Set up Python
uses: percona-platform/setup-python@v2
with:
python-version: '3.x'
#Configure git
- name: Configure git
env:
ROBOT_TOKEN: ${{ secrets.ROBOT_TOKEN }}
run: |
git config --global url."https://percona-platform-robot:${ROBOT_TOKEN}@github.com".insteadOf "https://github.com"
git config user.name "GitHub Action"
git config user.email "github-action@users.noreply.github.com"
git config user.password "${ROBOT_TOKEN}"
echo "GIT_USER=percona-platform-robot:${ROBOT_TOKEN}" >> $GITHUB_ENV
#Set up MkDocs
- name: Setup MkDocs
run: |
python -m pip install --upgrade pip
pip install wheel
if [ -f requirements-doc.txt ]; then pip install -r requirements-doc.txt; fi
# Deploy docs
- name: Deploy docs
run: |
mike deploy REL_1_STABLE -p
mike set-default REL_1_STABLE -p
mike retitle REL_1_STABLE "1.0.x (stable)" -p

14
CONTRIBUTING.md
View File

@ -118,19 +118,7 @@ The tests are run automatically with GitHub actions once you commit and push you
## Contributing to documentation
`pg_stat_monitor` documentation is written in Markdown language, so you can
[edit it online via GitHub](#edit-documentation-online-vi-github). Alternatively, you can include doc changes in your patch. The doc files are in the `docs` directory.
### Edit documentation online via GitHub
1. Click the **Edit this page** link on the sidebar. The source `.md` file of the page opens in GitHub editor in your browser. If you haven’t worked with the repository before, GitHub creates a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of it for you.
2. Edit the page. You can check your changes on the **Preview** tab.
3. Commit your changes.
* In the _Commit changes_ section, describe your changes.
* Select the **Create a new branch for this commit** and start a pull request option
* Click **Propose changes**.
4. GitHub creates a branch and a commit for your changes. It loads a new page on which you can open a pull request to Percona. The page shows the base branch - the one you offer your changes for, your commit message and a diff - a visual representation of your changes against the original page. This allows you to make a last-minute review. When you are ready, click the Create pull request button.
5. Someone from our team reviews the pull request and if everything is correct, merges it into the documentation. Then it gets published on the site.
`pg_stat_monitor` documentation is maintained in the [documentation repository](https://github.com/percona/pgsm-docs). Please read the [Contributing guide](https://github.com/percona/pgsm-docs/blob/main/CONTRIBUTING.md) for guidelines how you can contribute to the docs.
## After your pull request is merged

16
README.md
View File

@ -37,7 +37,7 @@
**NOTE**: The latest stable releases can be found underneath [Releases](https://github.com/percona/pg_stat_monitor/releases).
The `pg_stat_monitor` is a **_Query Performance Monitoring_** tool for PostgreSQL. It attempts to provide a more holistic picture by providing much-needed query performance insights in a [single view](https://github.com/percona/pg_stat_monitor/blob/master/docs/REFERENCE.md).
The `pg_stat_monitor` is a **_Query Performance Monitoring_** tool for PostgreSQL. It attempts to provide a more holistic picture by providing much-needed query performance insights in a [single view](https://docs.percona.com/pg-stat-monitor/reference.html).
`pg_stat_monitor` provides improved insights that allow database users to understand query origins, execution, planning statistics and details, query information, and metadata. This significantly improves observability, enabling users to debug and tune query performance. `pg_stat_monitor` is developed on the basis of `pg_stat_statements` as its more advanced replacement.
@ -45,7 +45,7 @@ While `pg_stat_statements` provides ever-increasing metrics, `pg_stat_monitor` a
>**NOTE**: Because of these differences in data processing, memory blocks and WAL (Write Ahead Logs) related statistics data are displayed inconsistently when both `pg_stat_monitor` and `pg_stat_statements` are used together.
To learn about other features, available in `pg_stat_monitor`, see the [Features](#pg_stat_monitor-features) section and the [User Guide](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md).
To learn about other features, available in `pg_stat_monitor`, see the [Features](#pg_stat_monitor-features) section and the [User Guide](https://docs.percona.com/pg-stat-monitor/user_guide.html).
`pg_stat_monitor` supports PostgreSQL versions 11 and above. It is compatible with both PostgreSQL provided by PostgreSQL Global Development Group (PGDG) and [Percona Distribution for PostgreSQL](https://www.percona.com/software/postgresql-distribution).
@ -78,9 +78,11 @@ The `pg_stat_monitor` should work on the latest version of both [Percona Distrib
### Documentation
1. [User guide](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md)
2. [Comparing `pg_stat_monitor` and `pg_stat_statements`](https://github.com/percona/pg_stat_monitor/blob/master/docs/COMPARISON.md)
3. [pg_stat_monitor view reference](https://github.com/percona/pg_stat_monitor/blob/master/docs/REFERENCE.md)
The following are useful links in [`pg_stat_monitor` documentation](https://docs.percona.com/pg-stat-monitor/index.html):
1. [User guide](https://docs.percona.com/pg-stat-monitor/user_guide.html)
2. [Comparing `pg_stat_monitor` and `pg_stat_statements`](https://docs.percona.com/pg-stat-monitor/comparison.html)
3. [pg_stat_monitor view reference](https://docs.percona.com/pg-stat-monitor/reference.html)
4. [Release notes](https://github.com/percona/pg_stat_monitor/blob/master/docs/RELEASE_NOTES.md)
5. [Contributing guide](https://github.com/percona/pg_stat_monitor/blob/master/CONTRIBUTING.md)
@ -153,7 +155,7 @@ pgxn install pg_stat_monitor
### Configuration
You can find the configuration parameters of the `pg_stat_monitor` extension in the `pg_stat_monitor_settings` view. To change the default configuration, specify new values for the desired parameters using the GUC (Grant Unified Configuration) system. To learn more, refer to the [Configuration](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md#configuration) section of the user guide.
You can find the configuration parameters of the `pg_stat_monitor` extension in the `pg_stat_monitor_settings` view. To change the default configuration, specify new values for the desired parameters using the GUC (Grant Unified Configuration) system. To learn more, refer to the [Configuration parameters](https://docs.percona.com/pg-stat-monitor/configuration.html) section of the documentation.
### Setup
@ -219,7 +221,7 @@ postgres=# SELECT application_name, userid AS user_name, datname AS database_nam
(5 rows)
```
To learn more about `pg_stat_monitor` features and usage, see [User Guide](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md). To view all other data elements provided by `pg_stat_monitor`, please see the reference.
To learn more about `pg_stat_monitor` features and usage, see the [User Guide](https://docs.percona.com/pg-stat-monitor/user_guide.html). To view all other data elements provided by `pg_stat_monitor`, please see the [reference](https://docs.percona.com/pg-stat-monitor/reference.html).
### Building from source

0
docs/RELEASE_NOTES.md → RELEASE_NOTES.md
View File

83
docs/COMPARISON.md
View File

@ -1,83 +0,0 @@
# Comparing pg_stat_monitor and pg_stat_statements
The `pg_stat_monitor` extension is developed on the basis of `pg_stat_statements` as its more advanced replacement.
Thus, `pg_stat_monitor` inherits the columns available in `pg_stat_statements` plus provides additional ones.
Note that [`pg_stat_monitor` and `pg_stat_statements` process statistics data differently](index.md#how-pg_stat_monitor-works). Because of these differences, memory blocks and WAL (Write Ahead Logs) related statistics data are displayed inconsistently when both extensions are used together.
To see all available columns, run the following command from the `psql` terminal:
```sql
postgres=# \d pg_stat_monitor;
```
The following table compares the `pg_stat_monitor` view with that of `pg_stat_statements`.
Note that the column names differ depending on the PostgreSQL version you are running.
| Column name for PostgreSQL 13 and above | Column name for PostgreSQL 11 and 12 | pg_stat_monitor | pg_stat_statements
|--------------------|--------------------------|-----------------------------|----------------------
bucket | bucket | :heavy_check_mark: | :x:
bucket_start_time | bucket_start_time | :heavy_check_mark: | :x:
userid | userid | :heavy_check_mark: | :heavy_check_mark:
datname | datname | :heavy_check_mark: | :heavy_check_mark:
toplevel[^1] | | :heavy_check_mark: | :heavy_check_mark:
client_ip | client_ip | :heavy_check_mark:| :x:
queryid | queryid | :heavy_check_mark: | :heavy_check_mark:
planid | planid | :heavy_check_mark:| :x:
query_plan | query_plan | :heavy_check_mark: | :x:
top_query | top_query | :heavy_check_mark: | :x:
top_queryid | top_queryid | :heavy_check_mark: | :x:
query | query | :heavy_check_mark: | :heavy_check_mark:
application_name | application_name | :heavy_check_mark:| :x:
relations | relations | :heavy_check_mark: | :x:
cmd_type | cmd_type | :heavy_check_mark: | :x:
elevel | elevel | :heavy_check_mark: | :x:
sqlcode | sqlcode | :heavy_check_mark: | :x:
message | message | :heavy_check_mark: | :x:
plans_calls | plans_calls | :heavy_check_mark: | :heavy_check_mark:
total_plan_time | | :heavy_check_mark: | :heavy_check_mark:
min_plan_time | | :heavy_check_mark: | :heavy_check_mark:
max_plan_time | | :heavy_check_mark: | :heavy_check_mark:
mean_plan_time | | :heavy_check_mark: | :heavy_check_mark:
stddev_plan_time | | :heavy_check_mark: | :heavy_check_mark:
calls | calls | :heavy_check_mark: | :heavy_check_mark:
total_exec_time | total_time | :heavy_check_mark: | :heavy_check_mark:
min_exec_time | min_time | :heavy_check_mark: | :heavy_check_mark:
max_exec_time | max_time | :heavy_check_mark: | :heavy_check_mark:
mean_exec_time | mean_time | :heavy_check_mark: | :heavy_check_mark:
stddev_exec_time | stddev_time | :heavy_check_mark: | :heavy_check_mark:
rows_retrieved | rows_retrieved | :heavy_check_mark: | :heavy_check_mark:
shared_blks_hit | shared_blks_hit | :heavy_check_mark: | :heavy_check_mark:
shared_blks_read | shared_blks_read | :heavy_check_mark: | :heavy_check_mark:
shared_blks_dirtied | shared_blks_dirtied | :heavy_check_mark: | :heavy_check_mark:
shared_blks_written | shared_blks_written | :heavy_check_mark: | :heavy_check_mark:
local_blks_hit | local_blks_hit | :heavy_check_mark: | :heavy_check_mark:
local_blks_read | local_blks_read | :heavy_check_mark: | :heavy_check_mark:
local_blks_dirtied | local_blks_dirtied | :heavy_check_mark: | :heavy_check_mark:
local_blks_written | local_blks_written | :heavy_check_mark: | :heavy_check_mark:
temp_blks_read | temp_blks_read | :heavy_check_mark: | :heavy_check_mark:
temp_blks_written | temp_blks_written | :heavy_check_mark:  | :heavy_check_mark:
blk_read_time | blk_read_time | :heavy_check_mark: | :heavy_check_mark:
blk_write_time | blk_write_time | :heavy_check_mark: | :heavy_check_mark:
resp_calls | resp_calls | :heavy_check_mark: | :x:
cpu_user_time | cpu_user_time | :heavy_check_mark: | :x:
cpu_sys_time | cpu_sys_time | :heavy_check_mark: | :x:
wal_records | wal_records | :heavy_check_mark:  | :heavy_check_mark:
wal_fpi | wal_fpi | :heavy_check_mark:  | :heavy_check_mark:
wal_bytes | wal_bytes | :heavy_check_mark:  | :heavy_check_mark:
state_code | state_code | :heavy_check_mark: | :x:
state | state | :heavy_check_mark: | :x:
To learn more about the features in `pg_stat_monitor`, please see the [User guide](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md).
Additional reading: [pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html)
[^1]: Available starting from PostgreSQL 14 and above

66
docs/REFERENCE.md
View File

@ -1,66 +0,0 @@
# `pg_stat_monitor` view reference
`pg_stat_monitor` provides a view where the statistics data is displayed. To see all available columns, run the following command from `psql`:
```sql
postgres=# \d pg_stat_monitor
```
Depending on the PostgreSQL version, some column names may differ. The following table describes the `pg_stat_monitor` view for PostgreSQL 14 and higher versions.
| Column | Type | Description
|--------------------|--------------------------|------------------
bucket | integer | Data collection unit. The number shows what bucket in a chain a record belongs to
bucket_start_time | timestamp with time zone | The start time of the bucket|
userid | regrole | An ID of the user who run a query |
datname | name | The name of a database where the query was executed
toplevel | bool | True means that a query was executed as a top-level statement
client_ip | inet | The IP address of a client that run the query
queryid | text | The internal hash code serving to identify every query in a statement
planid | text | An internally generated ID of a query plan
query_plan | text | The sequence of steps used to execute a query. This parameter is available only when the `pgsm_enable_query_plan` is enabled.
top_query | text | Shows the top query used in a statement |
query | text | The actual text of the query |
application_name | text | Shows the name of the application connected to the database
relations | text[] | The list of tables involved in the query
cmd_type | integer | Type of the query executed
cmd_type_text | text[] | The description of the query executed
elevel | integer | Shows the error level of a query (WARNING, ERROR, LOG)
sqlcode | integer | SQL error code
message | text | The error message
plans_calls | bigint | The number of times the statement was planned
total_plan_time | double precision | The total time (in ms) spent on planning the statement
min_plan_time | double precision | Minimum time (in ms) spent on planning the statement
max_plan_time | double precision | Maximum time (in ms) spent on planning the statement
mean_plan_time | double precision | The mean (average) time (in ms) spent on planning the statement
stddev_plan_time | double precision | The standard deviation of time (in ms) spent on planning the statement
calls | bigint | The number of times a particular query was executed
total_exec_time | double precision | The total time (in ms) spent on executing a query
min_exec_time | double precision | The minimum time (in ms) it took to execute a query
max_exec_time | double precision | The maximum time (in ms) it took to execute a query
mean_time | double precision | The mean (average) time (in ms) it took to execute a query
stddev_exec_time | double precision | The standard deviation of time (in ms) spent on executing a query
rows_retrieved | bigint | The number of rows retrieved when executing a query
shared_blks_hit | bigint | Shows the total number of shared memory blocks returned from the cache
shared_blks_read | bigint | Shows the total number of shared blocks returned not from the cache
shared_blks_dirtied | bigint | Shows the number of shared memory blocks "dirtied" by the query execution (i.e. a query modified at least one tuple in a block and this block must be written to a drive)
shared_blks_written | bigint | Shows the number of shared memory blocks written simultaneously to a drive during the query execution
local_blks_hit | bigint | The number of blocks which are considered as local by the backend and thus are used for temporary tables
local_blks_read | bigint | Total number of local blocks read during the query execution
local_blks_dirtied | bigint | Total number of local blocks "dirtied" during the query execution (i.e. a query modified at least one tuple in a block and this block must be written to a drive)
local_blks_written | bigint | Total number of local blocks written simultaneously to a drive during the query execution
temp_blks_read | bigint | Total number of blocks of temporary files read from a drive. Temporary files are used when there's not enough memory to execute a query
temp_blks_written | bigint | Total number of blocks of temporary files written to a drive
blk_read_time | double precision | Total waiting time (in ms) for reading blocks
blk_write_time | double precision | Total waiting time (in ms) for writing blocks to a drive
resp_calls | text[] | Call histogram
cpu_user_time | double precision | The time (in ms) the CPU spent on running the query
cpu_sys_time | double precision | The time (in ms) the CPU spent on executing the kernel code
wal_records | bigint | The total number of WAL (Write Ahead Logs) generated by the query
wal_fpi | bigint | The total number of WAL FPI (Full Page Images) generated by the query
wal_bytes | numeric | Total number of bytes used for the WAL generated by the query
state_code | bigint | Shows the state code of a query
state | text | The state message

699
docs/USER_GUIDE.md
View File

@ -1,699 +0,0 @@
# User Guide
* [Introduction](#introduction)
* [Features](#features)
* [Views](#views)
* [Functions](#functions)
* [Configuration](#configuration)
* [Usage examples](#usage-examples)
## Introduction
This document describes the features, functions and configuration of the ``pg_stat_monitor`` extension and gives some usage examples. For how to install and set up ``pg_stat_monitor``, see [Setting up](setup.md).
## Features
The following are the key features of pg_stat_monitor:
* [Time buckets](#time-buckets),
* [Table and index access statistics per statement](#table-and-index-access-statistics-per-statement),
* Query statistics:
* [Query and client information](#query-and-client-information),
* [Query timing information](#query-timing-information),
* [Query execution plan information](#query-execution-plan-information),
* [Use of actual data or parameters placeholders in queries](#use-of-actual-data-or-parameters-placeholders-in-queries),
* [Query type filtering](#query-type-filtering),
* [Query metadata supporting Google’s Sqlcommentor](#query-metadata),
* [Top query tracking](#top-query-tracking),
* [Relations](#relations) - showing tables involved in a query,
* [Monitoring of queries terminated with ERROR, WARNING and LOG error levels](#monitoring-of-queries-terminated-with-error-warning-and-log-error-levels),
* [Integration with Percona Monitoring and Management (PMM) tool](#integration-with-pmm),
* [Histograms](#histogram) - visual representation of query performance.
### Time buckets
Instead of supplying one set of ever-increasing counts, `pg_stat_monitor` computes stats for a configured number of time intervals; time buckets. This allows for much better data accuracy, especially in the case of high-resolution or unreliable networks.
Starting with release 1.1.0, buckets have fixed and consistent time windows. This enables external applications such as PMM to easily consume and chart the statistics data. To make this happen, the bucket start time is rounded down to the nearest bucket time size.
Note, however, that if you disable / enable the `pg_stat_monitor` at runtime, the first bucket may not contain all the data. For example, if `pg_stat_monitor` is enabled at 03:58:30, a 60-second bucket start time is set to 03:58:00 and this bucket may not contain the data for queries made between 03:58:00 and 03:58:30. To learn more about the bucket start time and size, see [pg_stat_monitor.pgsm_bucket_time](#pg_stat_monitorpgsm_bucket_time).
### Table and index access statistics per statement
`pg_stat_monitor` collects the information about what tables were accessed by a statement. This allows you to identify all queries which access a given table easily.
### Query and client information
`pg_stat_monitor` provides additional metrics for detailed analysis of query performance from various perspectives, including client connection details like user name, application name, IP address to name a few relevant columns.
With this information, `pg_stat_monitor` enables users to track a query to the originating application. More details about the application or query may be incorporated in the SQL query in a [Google’s Sqlcommenter](https://google.github.io/sqlcommenter/) format.
To see how it works, refer to the [usage example](#query-information)
### Query timing information
Understanding query execution time stats helps you identify what affects query performance and take measures to optimize it. `pg_stat_monitor` collects the total, min, max and average (mean) time it took to execute a particular query and provides this data in separate columns. See the [Query timing information](#query-timing-information-1) example for the sample output.
### Query execution plan information
Every query has a plan that was constructed for its executing. Collecting the query plan information as well as monitoring query plan timing helps you understand how you can modify the query to optimize its execution. It also helps make communication about the query clearer when discussing query performance with other DBAs and application developers.
See the [Query execution plan](##query-execution-plan) example for the sample output.
### Use of actual data or parameters placeholders in queries
You can select whether to see queries with parameters placeholders or actual query data. The benefit of having the full query example is in being able to run the [EXPLAIN](https://www.postgresql.org/docs/current/sql-explain.html) command on it to see how its execution was planned. As a result, you can modify the query to make it run better.
### Query type filtering
`pg_stat_monitor` monitors queries per type (``SELECT``, `INSERT`, `UPDATE` or `DELETE`) and classifies them accordingly in the `cmd_type` column. This way you can separate the queries you are interested in and focus on identifying the issues and optimizing query performance.
See the [Query type filtering example](#query-type-filtering-1) for the sample output.
### Query metadata
Google’s Sqlcommenter is a useful tool that in a way bridges that gap between ORM libraries and understanding database performance. And ``pg_stat_monitor`` supports it. So, you can now put any key-value data (like what client executed a query or if it is testing vs production query) in the comments in `/* … */` syntax in your SQL statements, and the information will be parsed by `pg_stat_monitor` and made available in the comments column in the `pg_stat_monitor` view. For details on the comments’ syntax, see [Sqlcommenter documentation](https://google.github.io/sqlcommenter/).
To see how it works, see the [Query metadata](#query-metadata-1) example.
### Top query tracking
Using functions is common. While running, functions can execute queries internally. `pg_stat_monitor` not only keeps track of all executed queries within a function, but also marks that function as top query.
Top query indicates the main query. To illustrate, for the SELECT query that is invoked within a function, the top query is calling this function.
This enables you to backtrack to the originating function and thus simplifies the tracking and analysis.
Find more details in the [usage example](#top-query-tracking-1).
### Relations
`pg_stat_monitor` provides the list of tables involved in the query in the relations column. This reduces time on identifying the tables and simplifies the analysis. To learn more, see the [usage examples](#relations-1)
### Monitoring queries terminated with ERROR, WARNING and LOG error levels
Monitoring queries that terminate with ERROR, WARNING, LOG states can give useful information to debug an issue. Such messages have the error level (`elevel`), error code (`sqlcode`), and error message (`message`). `pg_stat_monitor` collects all this information and aggregates it so that you can measure performance for successful and failed queries separately, as well as understand why a particular query failed to execute successfully.
Find details in the [usage example](#queries-terminated-with-errors)
### Integration with PMM
To timely identify and react on issues, performance should be automated and alerts should be sent when an issue occurs. There are many monitoring tools available for PostgreSQL, some of them (like Nagios) supporting custom metrics provided via extensions. Though you can integrate `pg_stat_monitor` with these tools, it natively supports integration with Percona Management and Monitoring (PMM). This integration allows you to enjoy all the features provided by both solutions: advanced statistics data provided by `pg_stat_monitor` and automated monitoring with data visualization on dashboards, security threat checks and alerting, available in PMM out of the box.
To learn how to integrate pg_stat_monitor with PMM, see [Configure pg_stat_monitor in PMM](https://www.percona.com/doc/percona-monitoring-and-management/2.x/setting-up/client/postgresql.html#pg_stat_monitor)
### Histogram
Histogram (the `resp_calls` parameter) provides a visual representation of query performance. With the help of the histogram function, you can view a timing/calling data histogram in response to an SQL query.
Learn more about using histograms from the [usage example](#histogram-1).
## Views
`pg_stat_monitor` provides the following views:
* `pg_stat_monitor` is the view where statistics data is presented.
* `pg_stat_monitor_settings` view shows available configuration options which you can change.
### `pg_stat_monitor` view
The statistics gathered by the module are made available via the view named `pg_stat_monitor`. This view contains one row for each distinct combination of metrics and whether it is a top-level statement or not (up to the maximum number of distinct statements that the module can track). For details about available counters, refer to the [`pg_stat_monitor` view reference](REFERENCE.md).
The following are the primary keys for pg_stat_monitor:
* `bucket`
* `userid`
* `datname`
* `queryid`
* `client_ip`
* `planid`
* `application_name`
* `toplevel`.
> **NOTE**: The `toplevel` key is considered starting with PostgreSQL 14 and above. For PostgreSQL 13 and earlier versions, the `toplevel` value is set to 1 by default, and thus, ignored.
A new row is created for each key in the `pg_stat_monitor` view.
`pg_stat_monitor` inherits the metrics available in `pg_stat_statements`, plus provides additional ones. See the [`pg_stat_monitor` vs `pg_stat_statements` comparison](COMPARISON.md) for details.
For security reasons, only superusers and members of the `pg_read_all_stats` role are allowed to see the SQL text and `queryid` of queries executed by other users. Other users can see the statistics, however, if the view has been installed in their database.
### pg_stat_monitor_settings view
The `pg_stat_monitor_settings` view shows one row per `pg_stat_monitor` configuration parameter. It displays configuration parameter name, value, default value, description, minimum and maximum values, and whether a restart is required for a change in value to be effective.
## Functions
### pg_stat_monitor_reset()
This function resets all the statistics and clears the view. Eventually, the function will delete all the previous data.
### pg_stat_monitor_version()
This function provides the build version of `pg_stat_monitor` version.
```
postgres=# select pg_stat_monitor_version();
pg_stat_monitor_version
-------------------------
devel
(1 row)
```
### histogram(bucket id, query id)
It is used to generate the histogram, you can refer to histogram sections.
## Configuration
Use the following command to view available configuration parameters in the `pg_stat_monitor_settings` view:
```sql
SELECT * FROM pg_stat_monitor_settings;
```
To amend the `pg_stat_monitor` configuration, use the General Configuration Unit (GCU) system. Some configuration parameters require the server restart and should be set before the server startup. These must be set in the `postgresql.conf` file. Other parameters do not require server restart and can be set permanently either in the `postgresql.conf` or from the client (`psql`) using the SET or ALTER SYSTEM SET commands.
The following table shows setup options for each configuration parameter and whether the server restart is required to apply the parameter's value:
| Parameter Name | postgresql.conf | SET | ALTER SYSTEM SET | server restart | configuration reload
| ----------------------------------------------|--------------------|-----|-------------------|-------------------|---------------------
| [pg_stat_monitor.pgsm_max](#pg_stat_monitorpgsm_max) | :heavy_check_mark: | :x: |:x: |:heavy_check_mark: | :x:
| [pg_stat_monitor.pgsm_query_max_len](#pg_stat_monitorpgsm_query_max_len) | :heavy_check_mark: | :x: |:x: |:heavy_check_mark: | :x:
| [pg_stat_monitor.pgsm_track_utility](#pg_stat_monitorpgsm_track_utility) | :heavy_check_mark: | :heavy_check_mark: |:heavy_check_mark: |:x: | :heavy_check_mark:
| [pg_stat_monitor.pgsm_normalized_query](#pg_stat_monitorpgsm_normalized_query) | :heavy_check_mark: | :heavy_check_mark: |:heavy_check_mark: |:x: | :heavy_check_mark:
| [pg_stat_monitor.pgsm_max_buckets](#pg_stat_monitorpgsm_max_buckets) | :heavy_check_mark: | :x: |:x: |:heavy_check_mark: | :heavy_check_mark:
| [pg_stat_monitor.pgsm_bucket_time](#pg_stat_monitorpgsm_bucket_time) | :heavy_check_mark: | :x: |:x: |:heavy_check_mark: | :x:
| [pg_stat_monitor.pgsm_histogram_min](#pg_stat_monitorpgsm_histogram_min) | :heavy_check_mark: | :x: |:x: |:heavy_check_mark: | :x:
| [pg_stat_monitor.pgsm_histogram_max](#pg_stat_monitorpgsm_histogram_max) | :heavy_check_mark: | :x: |:x: |:heavy_check_mark: | :x:
| [pg_stat_monitor.pgsm_histogram_buckets](#pg_stat_monitorpgsm_histogram_buckets) | :heavy_check_mark: | :x: |:x: |:heavy_check_mark: | :x:
| [pg_stat_monitor.pgsm_query_shared_buffer](#pg_stat_monitorpgsm_query_shared_buffer) | :heavy_check_mark: | :x: |:x: |:heavy_check_mark: | :x:
| [pg_stat_monitor.pgsm_overflow_target](#pg_stat_monitorpgsm_overflow_target) | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: | :x: |
| [pg_stat_monitor.pgsm_enable_query_plan](#pg_stat_monitorpgsm_enable_query_plan) | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: | :x: |
| [pg_stat_monitor.track](#pg_stat_monitortrack) | :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: |
| [pg_stat_monitor.extract_comments](#pg_stat_monitorextract_comments)| :heavy_check_mark: | :x: | :x: | :x: | :heavy_check_mark: |
| [pg_stat_monitor.pgsm_track_planning](#pg_stat_monitorpgsm_track_planning) | :heavy_check_mark: | :x: | :x: | :heavy_check_mark: | :x: |
#### Parameters description:
##### pg_stat_monitor.pgsm_max
Values:
- Min: 1
- Max: 1000
- Default: 100
This parameter defines the limit of shared memory (in MB) for ``pg_stat_monitor``. This memory is used by buckets in a circular manner. The memory is divided between the buckets equally, at the start of the PostgreSQL. Requires the server restart.
##### pg_stat_monitor.pgsm_query_max_len
Values:
- Min: 1024
- Max: 2147483647
- Default: 1024
Sets the maximum size of the query. This parameter can only be set at the start of PostgreSQL. For long queries, the query is truncated to that particular length. This is to avoid unnecessary usage of shared memory. Requires the server restart.
##### pg_stat_monitor.pgsm_track_utility
Type: boolean. Default: 1
This parameter controls whether utility commands are tracked by the module. Utility commands are all those other than ``SELECT``, ``INSERT``, ``UPDATE``, and ``DELETE``.
##### pg_stat_monitor.pgsm_normalized_query
Type: boolean. Default: 0
By default, the query shows the actual parameter instead of the placeholder. It is quite useful when users want to use that query and try to run that query to check the abnormalities. Users should be aware, however, that running queries with disabled normalization can expose some sensitive data.
But in most cases users like the queries with a placeholder. This parameter is used to toggle between the two said options.
##### pg_stat_monitor.pgsm_max_buckets
Values:
- Min: 1
- Max: 10
- Default: 10
``pg_stat_monitor`` accumulates the information in the form of buckets. All the aggregated information is bucket based. This parameter is used to set the number of buckets the system can have. For example, if this parameter is set to 2, then the system will create two buckets. First, the system will add all the information into the first bucket. After its lifetime (defined in the [pg_stat_monitor.pgsm_bucket_time](#pg-stat-monitorpgsm-bucket-time) parameter) expires, it will switch to the second bucket, reset all the counters and repeat the process.
Requires the server restart.
##### pg_stat_monitor.pgsm_bucket_time
Values:
- Min: 1
- Max: 2147483647
- Default: 60
This parameter sets the lifetime of the bucket. The system switches between buckets on the basis of [pg_stat_monitor.pgsm_bucket_time](#pg-stat-monitorpgsm-bucket-time).
Starting with release 1.1.0, the behavior of setting the bucket start time has changed. Previously, the bucket start time was aligned with the time of the first query arrived to that bucket. Now the bucket start time is rounded down to the bucket time size. To illustrate, if the first query arrives to a 60 second bucket at 03:01:15, the bucket start time is set to 03:01:00.
With this new behavior, buckets have now consistent time windows so that external applications such as PMM can easily consume the data in buckets.
Note that if you disable / enable the `pg_stat_monitor` at runtime, the first bucket may not contain all the data. Thus, if `pg_stat_monitor` is enabled at 03:58:30, the bucket start time is set to 03:58:00 but it will not contain the data for queries made between 03:58:00 and 03:58:30.
The parameter requires the server restart.
##### pg_stat_monitor.pgsm_histogram_min
Values:
- Min: 0
- Max: 2147483647
- Default: 0
``pg_stat_monitor`` also stores the execution time histogram. This parameter is used to set the lower bound of the histogram (in ms).
Requires the server restart.
##### pg_stat_monitor.pgsm_histogram_max
Values:
- Min: 10
- Max: 2147483647
- Default: 100000
This parameter sets the upper bound of the execution time histogram (in ms). Requires the server restart.
##### pg_stat_monitor.pgsm_histogram_buckets
Values:
- Min: 2
- Max: 2147483647
- Default: 10
This parameter sets the maximum number of histogram buckets. Requires the server restart.
##### pg_stat_monitor.pgsm_query_shared_buffer
Values:
- Min: 1
- Max: 10000
- Default: 20
This parameter defines the shared memory limit (in MB) allocated for a query tracked by ``pg_stat_monitor``. Requires the server restart.
##### pg_stat_monitor.pgsm_overflow_target
Type: boolean. Default: 1
Sets the overflow target for the `pg_stat_monitor`. Requires the server restart.
##### pg_stat_monitor.pgsm_enable_query_plan
Type: boolean. Default: 1
Enables or disables query plan monitoring. When the `pgsm_enable_query_plan` is disabled (0), the query plan will not be captured by `pg_stat_monitor`. Enabling it may adversely affect the database performance. Requires the server restart.
##### pg_stat_monitor.track
This parameter controls which statements are tracked by `pg_stat_monitor`.
Values:
- `top`: Default, track only top level queries (those issued directly by clients) and excludes listing nested statements (those called within a function).
- `all`: Track top along with sub/nested queries. As a result, some SELECT statement may be shown as duplicates.
- `none`: Disable query monitoring. The module is still loaded and is using shared memory, etc. It only silently ignores the capturing of data.
##### pg_stat_monitor.extract_comments
Type: boolean. Default: 0
This parameter controls whether to enable or disable extracting comments from queries.
##### pg_stat_monitor.pgsm_track_planning
Type: boolean. Default: 0
This parameter instructs ``pg_stat_monitor`` to monitor query planning statistics. Requires the server restart.
## Usage examples
Note that the column names differ depending on the PostgreSQL version you are using. The following usage examples are provided for PostgreSQL version 13.
For versions 11 and 12, please consult the [pg_stat_monitor reference](https://github.com/percona/pg_stat_monitor/blob/master/docs/REFERENCE.md).
### Querying buckets
```sql
postgres=# select bucket, bucket_start_time, query,calls from pg_stat_monitor order by bucket;
-[ RECORD 1 ]-----+------------------------------------------------------------------------------------
bucket | 0
bucket_start_time | 2021-10-22 11:10:00
query | select bucket, bucket_start_time, query,calls from pg_stat_monitor order by bucket;
calls | 1
```
The `bucket` parameter shows the number of a bucket for which a given record belongs.
The `bucket_start_time` shows the start time of the bucket.
`query` shows the actual query text.
`calls` shows how many times a given query was called.
### Query information
**Example 1: Shows the usename, database name, unique queryid hash, query, and the total number of calls of that query.**
```sql
postgres=# SELECT userid, datname, queryid, substr(query,0, 50) AS query, calls FROM pg_stat_monitor;
userid | datname | queryid | query | calls
---------+----------+------------------+---------------------------------------------------+-------
vagrant | postgres | 939C2F56E1F6A174 | END | 561
vagrant | postgres | 2A4437C4905E0E23 | SELECT abalance FROM pgbench_accounts WHERE aid = | 561
vagrant | postgres | 4EE9ED0CDF143477 | SELECT userid, datname, queryid, substr(query,$1 | 1
vagrant | postgres | 8867FEEB8A5388AC | vacuum pgbench_branches | 1
vagrant | postgres | 41D1168FB0733CAB | select count(*) from pgbench_branches | 1
vagrant | postgres | E5A889A8FF37C2B1 | UPDATE pgbench_accounts SET abalance = abalance + | 561
vagrant | postgres | 4876BBA9A8FCFCF9 | truncate pgbench_history | 1
vagrant | postgres | 22B76AE84689E4DC | INSERT INTO pgbench_history (tid, bid, aid, delta | 561
vagrant | postgres | F6DA9838660825CA | vacuum pgbench_tellers | 1
vagrant | postgres | 214646CE6F9B1A85 | BEGIN | 561
vagrant | postgres | 27462943E814C5B5 | UPDATE pgbench_tellers SET tbalance = tbalance + | 561
vagrant | postgres | 4F66D46F3D4151E | SELECT userid, dbid, queryid, substr(query,0, 50 | 1
vagrant | postgres | 6A02C123488B95DB | UPDATE pgbench_branches SET bbalance = bbalance + | 561
(13 rows)
```
**Example 2: Shows the connected application details.**
```sql
postgres=# SELECT application_name, client_ip, substr(query,0,100) as query FROM pg_stat_monitor;
application_name | client_ip | query
------------------+-----------+-----------------------------------------------------------------------------------------------------
pgbench | 127.0.0.1 | truncate pgbench_history
pgbench | 127.0.0.1 | SELECT abalance FROM pgbench_accounts WHERE aid = $1
pgbench | 127.0.0.1 | UPDATE pgbench_accounts SET abalance = abalance + $1 WHERE aid = $2
pgbench | 127.0.0.1 | BEGIN;
pgbench | 127.0.0.1 | INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES ($1, $2, $3, $4, CURRENT_TIMESTAMP
pgbench | 127.0.0.1 | END;
pgbench | 127.0.0.1 | vacuum pgbench_branches
pgbench | 127.0.0.1 | UPDATE pgbench_tellers SET tbalance = tbalance + $1 WHERE tid = $2
pgbench | 127.0.0.1 | vacuum pgbench_tellers
pgbench | 127.0.0.1 | UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2
pgbench | 127.0.0.1 | select o.n, p.partstrat, pg_catalog.count(i.inhparent) from pg_catalog.pg_class as c join pg_catalo
psql | 127.0.0.1 | SELECT application_name, client_ip, substr(query,$1,$2) as query FROM pg_stat_monitor
pgbench | 127.0.0.1 | select count(*) from pgbench_branches
(13 rows)
```
### Query timing information
```sql
SELECT userid, total_time, min_time, max_time, mean_time, query FROM pg_stat_monitor;
userid | total_time | min_time | max_time | mean_time | query
--------+--------------------+--------------------+--------------------+--------------------+------------------------------------------------------------------
10 | 0.14 | 0.14 | 0.14 | 0.14 | select * from pg_stat_monitor_reset()
10 | 0.19 | 0.19 | 0.19 | 0.19 | select userid, dbid, queryid, query from pg_stat_monitor
10 | 0.30 | 0.13 | 0.16 | 0.15 | select bucket, bucket_start_time, query from pg_stat_monitor
10 | 0.29 | 0.29 | 0.29 | 0.29 | select userid, dbid, queryid, query, calls from pg_stat_monitor
10 | 11277.79 | 11277.79 | 11277.79 |
```
### Query execution plan
```sql
postgres=# SELECT substr(query,0,50), query_plan from pg_stat_monitor limit 10;
substr | query_plan
---------------------------------------------------+---------------------------------------------------------------------------------------------------------------
select o.n, p.partstrat, pg_catalog.count(i.inhpa | Limit +
| -> GroupAggregate +
| Group Key: (array_position(current_schemas(true), n.nspname)), p.partstrat +
| -> Sort +
| Sort Key: (array_position(current_schemas(true), n.nspname)), p.partstrat +
| -> Nested Loop Left Join +
| -> Nested Loop Left Join +
| -> Nested Loop +
| Join Filter: (c.relnamespace = n.oid) +
| -> Index Scan using pg_class_relname_nsp_index on pg_class c +
| Index Cond: (relname = 'pgbench_accounts'::name) +
| -> Seq Scan on pg_namespace n +
| Filter: (array_position(current_schemas(true), nspname) IS NOT NULL) +
| -> Index Scan using pg_partitioned_table_partrelid_index on pg_partitioned_table p+
| Index Cond: (partrelid = c.oid) +
| -> Bitmap Heap Scan on pg_inherits i +
| R
SELECT abalance FROM pgbench_accounts WHERE aid = | Index Scan using pgbench_accounts_pkey on pgbench_accounts +
| Index Cond: (aid = 102232)
BEGIN; |
END; |
SELECT substr(query,$1,$2), query_plan from pg_st |
SELECT substr(query,$1,$2),calls, planid,query_pl | Limit +
| -> Subquery Scan on pg_stat_monitor +
| -> Result +
| -> Sort +
| Sort Key: p.bucket_start_time +
| -> Hash Join +
| Hash Cond: (p.dbid = d.oid) +
| -> Function Scan on pg_stat_monitor_internal p +
| -> Hash +
| -> Seq Scan on pg_database d +
| SubPlan 1 +
| -> Function Scan on pg_stat_monitor_internal s +
| Filter: (queryid = p.top_queryid)
select count(*) from pgbench_branches | Aggregate +
| -> Seq Scan on pgbench_branches
UPDATE pgbench_tellers SET tbalance = tbalance + |
vacuum pgbench_tellers |
UPDATE pgbench_accounts SET abalance = abalance + |
(10 rows)
```
The `plan` column does not contain costing, width and other values. This is an expected behavior as each row is an accumulation of statistics based on `plan` and amongst other key columns. Plan is only available when the `pgsm_enable_query_plan` configuration parameter is enabled.
### Query type filtering
``pg_stat_monitor`` monitors queries per type (SELECT, INSERT, UPDATE OR DELETE) and classifies them accordingly in the ``cmd_type`` column thus reducing your efforts.
```sql
postgres=# SELECT bucket, substr(query,0, 50) AS query, cmd_type FROM pg_stat_monitor WHERE elevel = 0;
bucket | query | cmd_type
--------+---------------------------------------------------+----------
4 | END |
4 | SELECT abalance FROM pgbench_accounts WHERE aid = | SELECT
4 | vacuum pgbench_branches |
4 | select count(*) from pgbench_branches | SELECT
4 | UPDATE pgbench_accounts SET abalance = abalance + | UPDATE
4 | truncate pgbench_history |
4 | INSERT INTO pgbench_history (tid, bid, aid, delta | INSERT
5 | SELECT relations query FROM pg_stat_monitor | SELECT
9 | SELECT bucket, substr(query,$1, $2) AS query, cmd |
4 | vacuum pgbench_tellers |
4 | BEGIN |
5 | SELECT relations,query FROM pg_stat_monitor | SELECT
4 | UPDATE pgbench_tellers SET tbalance = tbalance + | UPDATE
4 | UPDATE pgbench_branches SET bbalance = bbalance + | UPDATE
(14 rows)
```
### Query metadata
The `comments` column contains any text wrapped in `“/*”` and `“*/”` comment tags. The `pg_stat_monitor` extension picks up these comments and makes them available in the comments column. Please note that only the latest comment value is preserved per row. The comments may be put in any format that can be parsed by a tool.
```sql
CREATE EXTENSION hstore;
CREATE FUNCTION text_to_hstore(s text) RETURNS hstore AS $$
BEGIN
RETURN hstore(s::text[]);
EXCEPTION WHEN OTHERS THEN
RETURN NULL;
END; $$ LANGUAGE plpgsql STRICT;
postgres=# SELECT 1 AS num /* { "application", java_app, "real_ip", 192.168.1.1} */;
num
-----
1
(1 row)
postgres=# SELECT 1 AS num1,2 AS num2 /* { "application", java_app, "real_ip", 192.168.1.2} */;
num1 | num2
------+------
1 | 2
(1 row)
postgres=# SELECT 1 AS num1,2 AS num2, 3 AS num3 /* { "application", java_app, "real_ip", 192.168.1.3} */;
num1 | num2 | num3
------+------+------
1 | 2 | 3
(1 row)
postgres=# SELECT 1 AS num1,2 AS num2, 3 AS num3, 4 AS num4 /* { "application", psql_app, "real_ip", 192.168.1.3} */;
num1 | num2 | num3 | num4
------+------+------+------
1 | 2 | 3 | 4
(1 row)
postgres=# select query, text_to_hstore(comments) as comments_tags from pg_stat_monitor;
query | comments_tags
---------------------------------------------------------------------------------------------------------------+-----------------------------------------------------
SELECT $1 AS num /* { "application", psql_app, "real_ip", 192.168.1.3) */ | "real_ip"=>"192.168.1.1", "application"=>"java_app"
SELECT pg_stat_monitor_reset(); |
select query, comments, text_to_hstore(comments) from pg_stat_monitor; |
SELECT $1 AS num1,$2 AS num2, $3 AS num3 /* { "application", java_app, "real_ip", 192.168.1.3} */ | "real_ip"=>"192.168.1.3", "application"=>"java_app"
select query, text_to_hstore(comments) as comments_tags from pg_stat_monitor; |
SELECT $1 AS num1,$2 AS num2 /* { "application", java_app, "real_ip", 192.168.1.2} */ | "real_ip"=>"192.168.1.2", "application"=>"java_app"
SELECT $1 AS num1,$2 AS num2, $3 AS num3, $4 AS num4 /* { "application", psql_app, "real_ip", 192.168.1.3} */ | "real_ip"=>"192.168.1.3", "application"=>"psql_app"
(7 rows)
postgres=# select query, text_to_hstore(comments)->'application' as application_name from pg_stat_monitor;
query | application_name
---------------------------------------------------------------------------------------------------------------+----------
SELECT $1 AS num /* { "application", psql_app, "real_ip", 192.168.1.3) */ | java_app
SELECT pg_stat_monitor_reset(); |
select query, text_to_hstore(comments)->"real_ip" as comments_tags from pg_stat_monitor; |
select query, text_to_hstore(comments)->$1 from pg_stat_monitor |
select query, text_to_hstore(comments) as comments_tags from pg_stat_monitor; |
select query, text_to_hstore(comments)->"application" as comments_tags from pg_stat_monitor; |
SELECT $1 AS num1,$2 AS num2 /* { "application", java_app, "real_ip", 192.168.1.2} */ | java_app
SELECT $1 AS num1,$2 AS num2, $3 AS num3 /* { "application", java_app, "real_ip", 192.168.1.3} */ | java_app
select query, comments, text_to_hstore(comments) from pg_stat_monitor; |
SELECT $1 AS num1,$2 AS num2, $3 AS num3, $4 AS num4 /* { "application", psql_app, "real_ip", 192.168.1.3} */ | psql_app
(10 rows)
postgres=# select query, text_to_hstore(comments)->'real_ip' as real_ip from pg_stat_monitor;
query | real_ip
---------------------------------------------------------------------------------------------------------------+-------------
SELECT $1 AS num /* { "application", psql_app, "real_ip", 192.168.1.3) */ | 192.168.1.1
SELECT pg_stat_monitor_reset(); |
select query, text_to_hstore(comments)->"real_ip" as comments_tags from pg_stat_monitor; |
select query, text_to_hstore(comments)->$1 from pg_stat_monitor |
select query, text_to_hstore(comments) as comments_tags from pg_stat_monitor; |
select query, text_to_hstore(comments)->"application" as comments_tags from pg_stat_monitor; |
SELECT $1 AS num1,$2 AS num2 /* { "application", java_app, "real_ip", 192.168.1.2} */ | 192.168.1.2
SELECT $1 AS num1,$2 AS num2, $3 AS num3 /* { "application", java_app, "real_ip", 192.168.1.3} */ | 192.168.1.3
select query, comments, text_to_hstore(comments) from pg_stat_monitor; |
SELECT $1 AS num1,$2 AS num2, $3 AS num3, $4 AS num4 /* { "application", psql_app, "real_ip", 192.168.1.3} */ | 192.168.1.3
(10 rows)
```
### Top query tracking
In the following example we create a function `add2` that adds one parameter value to another one and call this function to calculate 1+2.
```sql
CREATE OR REPLACE function add2(int, int) RETURNS int as
$$
BEGIN
return (select $1 + $2);
END;
$$ language plpgsql;
SELECT add2(1,2);
add2
-----
3
(1 row)
The ``pg_stat_monitor`` view shows all executed queries and shows the very first query in a row - calling the `add2` function.
postgres=# SELECT queryid, top_queryid, query, top_query FROM pg_stat_monitor;
queryid | top_queryid | query. | top_query
------------------+------------------+-------------------------------------------------------------------------+-------------------
3408CA84B2353094 | | select add2($1,$2) |
762B99349F6C7F31 | 3408CA84B2353094 | SELECT (select $1 + $2) | select add2($1,$2)
(2 rows)
```
### Relations
**Example 1: List all the table names involved in the query.**
```sql
postgres=# SELECT relations,query FROM pg_stat_monitor;
relations | query
-------------------------------+------------------------------------------------------------------------------------------------------
| END
{public.pgbench_accounts} | SELECT abalance FROM pgbench_accounts WHERE aid = $1
| vacuum pgbench_branches
{public.pgbench_branches} | select count(*) from pgbench_branches
{public.pgbench_accounts} | UPDATE pgbench_accounts SET abalance = abalance + $1 WHERE aid = $2
| truncate pgbench_history
{public.pgbench_history} | INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES ($1, $2, $3, $4, CURRENT_TIMESTAMP)
{public.pg_stat_monitor,pg_catalog.pg_database} | SELECT relations query FROM pg_stat_monitor
| vacuum pgbench_tellers
| BEGIN
{public.pgbench_tellers} | UPDATE pgbench_tellers SET tbalance = tbalance + $1 WHERE tid = $2
{public.pgbench_branches} | UPDATE pgbench_branches SET bbalance = bbalance + $1 WHERE bid = $2
(12 rows)
```
**Example 2: List all the views and the name of the table in the view. Here we have a view "test_view"**
```sql
\d+ test_view
View "public.test_view"
Column | Type | Collation | Nullable | Default | Storage | Description
--------+---------+-----------+----------+---------+---------+-------------
foo_a | integer | | | | plain |
bar_a | integer | | | | plain |
View definition:
SELECT f.a AS foo_a,
b.a AS bar_a
FROM foo f,
bar b;
```
Now when we query the ``pg_stat_monitor``, it will show the view name and also all the table names in the view. Note that the view name is followed by an asterisk (*).
```sql
SELECT relations, query FROM pg_stat_monitor;
relations | query
---------------------+----------------------------------------------------
{test_view*,foo,bar} | select * from test_view
{foo,bar} | select * from foo,bar
(2 rows)
```
### Queries terminated with errors
```sql
SELECT substr(query,0,50) AS query, decode_error_level(elevel) AS elevel,sqlcode, calls, substr(message,0,50) message
FROM pg_stat_monitor;
query | elevel | sqlcode | calls | message
---------------------------------------------------+--------+---------+-------+---------------------------------------------------
select substr(query,$1,$2) as query, decode_error | | 0 | 1 |
select bucket,substr(query,$1,$2),decode_error_le | | 0 | 3 |
| LOG | 0 | 1 | database system is ready to accept connections
select 1/0; | ERROR | 130 | 1 | division by zero
| LOG | 0 | 1 | database system was shut down at 2020-11-11 11:37
select $1/$2 | | 0 | 1 |
(6 rows)
11277.79 | SELECT * FROM foo
```
### Histogram
Histogram (the `resp_calls` parameter) provides a visual representation of query performance. With the help of the histogram function, you can view a timing/calling data histogram in response to a SQL query.
```sql
SELECT resp_calls, query FROM pg_stat_monitor;
                    resp_calls                    |                 query                                        
--------------------------------------------------+----------------------------------------------
{1," 0"," 0"," 0"," 0"," 0"," 0"," 0"," 0"," 0"} | select client_ip, query from pg_stat_monitor
{3," 0"," 0"," 0"," 0"," 0"," 0"," 0"," 0"," 1"} | select * from pg_stat_monitor_reset()
{3," 0"," 0"," 0"," 0"," 0"," 0"," 0"," 0"," 1"} | SELECT * FROM foo
postgres=# SELECT * FROM histogram(0, 'F44CD1B4B33A47AF') AS a(range TEXT, freq INT, bar TEXT);
range | freq | bar
--------------------+------+--------------------------------
(0 - 3)} | 2 | ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■
(3 - 10)} | 0 |
(10 - 31)} | 1 | ■■■■■■■■■■■■■■■
(31 - 100)} | 0 |
(100 - 316)} | 0 |
(316 - 1000)} | 0 |
(1000 - 3162)} | 0 |
(3162 - 10000)} | 0 |
(10000 - 31622)} | 0 |
(31622 - 100000)} | 0 |
(10 rows)
```
There are 10 time based buckets of the time generated automatically based on total buckets in the field ``resp_calls``. The value in the field shows how many queries run in that period of time.

BIN
docs/_images/percona-favicon.ico
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 15 KiB

12
docs/_images/percona-logo.svg
View File

@ -1,12 +0,0 @@
<svg width="74" height="74" viewBox="0 0 74 74" fill="none" xmlns="http://www.w3.org/2000/svg">
<circle cx="37" cy="37" r="37" fill="url(#paint0_linear)"/>
<path d="M37.5003 58C49.3744 58 59 48.3743 59 36.5C59 24.6257 49.3744 15 37.5003 15C25.6261 15 16 24.6257 16 36.5C16 36.6671 16.0019 36.8338 16.0057 37H16V67.4672C18.744 69.3622 21.7566 70.896 24.969 72H25V53.9948C28.5225 56.5161 32.8381 58 37.5003 58Z" fill="white"/>
<path d="M50 36.5C50 43.4036 44.4037 49 37.5001 49C30.5966 49 25 43.4036 25 36.5C25 29.5964 30.5966 24 37.5001 24C44.4037 24 50 29.5964 50 36.5Z" fill="#FCB42F"/>
<defs>
<linearGradient id="paint0_linear" x1="37" y1="0" x2="37" y2="74" gradientUnits="userSpaceOnUse">
<stop stop-color="#FBB32F"/>
<stop offset="0.504739" stop-color="#C11511"/>
<stop offset="1" stop-color="#C11411"/>
</linearGradient>
</defs>
</svg>
Side by Side

Before

Width:  |  Height:  |  Size: 878 B

16
docs/css/percona.css
View File

@ -1,16 +0,0 @@
[data-md-color-scheme="percona-light"] {
--md-primary-fg-color: #e97e03;
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
}
[data-md-color-scheme="slate"] {
--md-primary-fg-color: #e97e03;
/*
--md-primary-fg-color--light: #ECB7B7;
--md-primary-fg-color--dark: #90030C;
*/
--md-hue: 210; /* [0, 360] */
}
ul li p {
margin: 0;
}

48
docs/css/toctree.css
View File

@ -1,48 +0,0 @@
.sphinxsidebarwrapper {
padding-right: 0 !important;
}
/* Turns off bullets within toctree */
.sphinxsidebarwrapper ul {
list-style: none;
}
.sphinxsidebarwrapper>ul {
padding-left: 0;
}
.sphinxsidebarwrapper>ul>li {
padding: 0 0 10px 0;
margin: 0;
}
.custom-button {
cursor: pointer;
display: inline-flex;
justify-content: center;
align-items: center;
width: 10px;
margin-right: 5px;
margin-bottom: 0;
font-size: 18px;
font-weight: 400;
border: none;
background-color: transparent;
outline: none;
}
.custom-button~ul {
display: none;
}
.custom-button--main-active {
background-color: #e3e3e3
}
.custom-button.custom-button--active~ul {
display: block;
}
.custom-button:before {
content: '+';
}
.custom-button.custom-button--active:before {
content: '-';
}

54
docs/index.md
View File

@ -1,54 +0,0 @@
# Welcome
The **pg_stat_monitor** is a **_Query Performance Monitoring_** tool for PostgreSQL. It collects performance stats and provides query performance insights in a single view. These insights allow database users to understand query origins, execution, planning statistics and details, query information, and metadata. This significantly improves observability, enabling users to debug and tune query performance.
## How `pg_stat_monitor` works?
`pg_stat_monitor` is developed on the basis of `pg_stat_statements` as its more advanced replacement. While `pg_stat_statements` provides ever-increasing metrics, `pg_stat_monitor` aggregates the collected data, saving user efforts for doing it themselves. `pg_stat_monitor` stores statistics in configurable time-based units – _buckets_. Such bucket-based data collection allows focusing on statistics generated for shorter time periods and makes query timing information such as max/min/mean time more accurate.
## Features
* **Time Interval Grouping:** Instead of supplying one set of ever-increasing counts, `pg_stat_monitor` computes stats for a configured number of time intervals - time buckets. This allows for much better data accuracy, especially in the case of high resolution or unreliable networks.
* **Multi-Dimensional Grouping:** While `pg_stat_statements` groups counters by userid, dbid, queryid, `pg_stat_monitor` uses a more detailed group for higher precision. This allows a user to drill down into the performance of queries.
* **Capture Actual Parameters in the Queries:** `pg_stat_monitor` allows you to choose if you want to see queries with placeholders for parameters or actual parameter data. This simplifies debugging and analysis processes by enabling users to execute the same query.
* **Query Plan:** Each SQL is now accompanied by its actual plan that was constructed for its execution. That's a huge advantage if you want to understand why a particular query is slower than expected.
* **Tables Access Statistics for a Statement:** This allows us to easily identify all queries that accessed a given table. This set is at par with the information provided by the `pg_stat_statements`.
* **Histogram:** Visual representation is very helpful as it can help identify issues. With the help of the histogram function, one can now view a timing/calling data histogram in response to an SQL query. And yes, it even works in psql.
## Availability
`pg_stat_monitor` supports PostgreSQL versions 11 and above. It is compatible with both PostgreSQL provided by PostgreSQL Global Development Group (PGDG) and [Percona Distribution for PostgreSQL](https://www.percona.com/software/postgresql-distribution).
### Supported versions
The `pg_stat_monitor` should work on the latest version of both [Percona Distribution for PostgreSQL](https://www.percona.com/software/postgresql-distribution) and PostgreSQL, but is only tested with these versions:
| **Distribution** | **Version** | **Provider** |
| ---------------- | --------------- | ------------ |
|[Percona Distribution for PostgreSQL](https://www.percona.com/software/postgresql-distribution)| [11](https://www.percona.com/downloads/percona-postgresql-11/LATEST/), [12](https://www.percona.com/downloads/postgresql-distribution-12/LATEST/), [13](https://www.percona.com/downloads/postgresql-distribution-13/LATEST/) and [14](https://www.percona.com/downloads/postgresql-distribution-14/LATEST/)| Percona|
| PostgreSQL | 11, 12, 13 and 14 | PostgreSQL Global Development Group (PGDG) |
The RPM (for RHEL and CentOS) and the DEB (for Debian and Ubuntu) packages are available from Percona repositories for PostgreSQL versions [11](https://www.percona.com/downloads/percona-postgresql-11/LATEST/), [12](https://www.percona.com/downloads/postgresql-distribution-12/LATEST/), [13](https://www.percona.com/downloads/postgresql-distribution-13/LATEST/) and [14](https://www.percona.com/downloads/postgresql-distribution-14/LATEST/).
The RPM packages are also available in the official PostgreSQL (PGDG) `yum` repositories.
## Get started
* Use the [installation guidelines](setup.md) to install and set up `pg_stat_monitor`.
* Refer to the [User guide](USER_GUIDE.md) for details about available features and functions, usage examples and configuration parameters.
## Get engaged
* Use the [contributing guide](https://github.com/percona/pg_stat_monitor/blob/main/CONTRIBUTING.md) to learn how to become a contributor.
* Use the [forum](https://forums.percona.com/c/postgresql/pg-stat-monitor/69) to discuss a topic with the community.
## Read more
* [`pg_stat_monitor` view reference](REREFENCE.md)
* [pg_stat_monitor and pg_stat_statements comparison](COMPARE.md)

120
docs/js/version-select.js
View File

@ -1,120 +0,0 @@
setTimeout(() => {
const asideMenu = document.getElementsByClassName('sphinxsidebarwrapper')[0];
hideSubMenus();
asideMenu.style.display = 'block';
}, 500);
function hideSubMenus() {
const asideMenu = document.getElementsByClassName('sphinxsidebarwrapper')[0];
const activeCheckboxClass = 'custom-button--active';
const activeBackgroundClass = 'custom-button--main-active';
const links = Array.from(asideMenu.getElementsByTagName('a'));
const accordionLinks = links.filter(links => links.nextElementSibling && links.nextElementSibling.localName === 'ul');
const simpleLinks = links.filter(links => !links.nextElementSibling && links.parentElement.localName === 'li');
simpleLinks.forEach(simpleLink => {
simpleLink.parentElement.style.listStyleType = 'disc';
simpleLink.parentElement.style.marginLeft = '20px';
});
accordionLinks.forEach((link, index) => {
insertButton(link, index);
});
const buttons = Array.from(document.getElementsByClassName('custom-button'));
buttons.forEach(button => button.addEventListener('click', event => {
event.preventDefault();
const current = event.currentTarget;
const parent = current.parentElement;
const isMain = Array.from(parent.classList).includes('toctree-l1');
const isMainActive = Array.from(parent.classList).includes(activeBackgroundClass);
const targetClassList = Array.from(current.classList);
toggleElement(targetClassList.includes(activeCheckboxClass), current, activeCheckboxClass);
if (isMain) {
toggleElement(isMainActive, parent, activeBackgroundClass);
}
}));
// WIP var toctree_heading = document.getElementById("toctree-heading");
// NOT NEEDED? asideMenu.parentNode.insertBefore(styleDomEl, asideMenu);
}
function toggleElement(condition, item, className) {
const isButton = item.localName === 'button';
if (!condition) {
const previousActive = Array.from(item.parentElement.parentElement.getElementsByClassName('list-item--active'));
if (isButton) {
localStorage.setItem(item.id, 'true');
if (previousActive.length) {
previousActive.forEach(previous => {
const previousActiveButtons = Array.from(previous.getElementsByClassName('custom-button--active'));
removeClass(previous, ['list-item--active', 'custom-button--main-active']);
if (previousActiveButtons.length) {
previousActiveButtons.forEach(previousButton => {
removeClass(previousButton, 'custom-button--active');
localStorage.removeItem(previousButton.id);
});
}
})
}
}
addClass(item, className);
addClass(item.parentElement, 'list-item--active');
} else {
removeClass(item, className);
removeClass(item.parentElement, 'list-item--active');
if (isButton) {
localStorage.removeItem(item.id);
}
}
}
function addClass(item, classes) {
item.classList.add(...Array.isArray(classes) ? classes : [classes]);
}
function removeClass(item, classes) {
item.classList.remove(...Array.isArray(classes) ? classes : [classes]);
}
function insertButton(element, id) {
const button = document.createElement('button');
const isMain = Array.from(element.parentElement.classList).includes('toctree-l1');
button.id = id;
addClass(button, 'custom-button');
if (localStorage.getItem(id)) {
addClass(button, 'custom-button--active');
addClass(element.parentElement, 'list-item--active');
if (isMain) {
addClass(element.parentElement, 'custom-button--main-active');
}
}
element.insertAdjacentElement('beforebegin', button);
}
function makeSelect() {
const custom_select = document.getElementById('custom_select');
const select_active_option = custom_select.getElementsByClassName('select-active-text')[0];
const custom_select_list = document.getElementById('custom_select_list');
select_active_option.innerHTML = window.location.href.includes('') ?
custom_select_list.getElementsByClassName('custom-select__option')[1].innerHTML :
custom_select_list.getElementsByClassName('custom-select__option')[0].innerHTML;
document.addEventListener('click', event => {
if (event.target.parentElement.id === 'custom_select' || event.target.id === 'custom_select') {
custom_select_list.classList.toggle('select-hidden')
}
if (Array.from(event.target.classList).includes('custom-select__option')) {
select_active_option.innerHTML = event.target.innerHTML;
}
if (event.target.id !== 'custom_select' && event.target.parentElement.id !== 'custom_select') {
custom_select_list.classList.add('select-hidden')
}
});
}

9
docs/overrides/404.html
View File

@ -1,9 +0,0 @@
{#-
This file was automatically generated - do not edit
-#}
{% extends "main.html" %}
{% block content %}
<h1>404 - Not found</h1>
<p>
We can't find the page you are looking for. Try using the Search or <a href= "{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"> return to homepage </a>. </p>
{% endblock %}

208
docs/setup.md
View File

@ -1,208 +0,0 @@
# Setting up `pg_stat_monitor`
## Supported platforms
The PostgreSQL YUM repository supports `pg_stat_monitor` for all [supported versions](#supported-versions) for the following platforms:
* Red Hat Enterprise/Rocky/CentOS/Oracle Linux 7 and 8
* Fedora 33 and 34
Find the list of supported platforms for `pg_stat_monitor` within [Percona Distribution for PostgreSQL](https://www.percona.com/software/postgresql-distribution) on the [Percona Release Lifecycle Overview](https://www.percona.com/services/policies/percona-software-support-lifecycle#pgsql) page.
## Installation guidelines
You can install `pg_stat_monitor` from the following sources:
* [Percona repositories](#installing-from-percona-repositories),
* [PostgreSQL PGDG yum repositories](#installing-from-postgresql-yum-repositories),
* [PGXN](#installing-from-pgxn) and
* [source code](#building-from-source).
### Installing from Percona repositories
To install `pg_stat_monitor` from Percona repositories, you need to use the `percona-release` repository management tool.
1. [Install percona-release](https://www.percona.com/doc/percona-repo-config/installing.html) following the instructions relevant to your operating system
2. Enable Percona repository:
``` sh
percona-release setup ppgXX
```
Replace XX with the desired PostgreSQL version. For example, to install `pg_stat_monitor ` for PostgreSQL 13, specify `ppg13`.
3. Install `pg_stat_monitor` package
* For Debian and Ubuntu:
``` sh
apt-get install percona-pg-stat-monitor13
```
* For RHEL and CentOS:
``` sh
yum install percona-pg-stat-monitor13
```
### Installing from PostgreSQL `yum` repositories
Install the PostgreSQL repositories following the instructions in the [Linux downloads (Red Hat family)](https://www.postgresql.org/download/linux/redhat/) chapter in PostgreSQL documentation.
Install `pg_stat_monitor`:
```
dnf install -y pg_stat_monitor_<VERSION>
```
Replace the `VERSION` variable with the PostgreSQL version you are using (e.g. specify `pg_stat_monitor_13` for PostgreSQL 13)
### Installing from PGXN
You can install `pg_stat_monitor` from PGXN (PostgreSQL Extensions Network) using the [PGXN client](https://pgxn.github.io/pgxnclient/).
Use the following command:
```
pgxn install pg_stat_monitor
```
### Building from source
To build `pg_stat_monitor` from source code, you require the following:
* git
* make
* gcc
* pg_config
You can download the source code of the latest release of `pg_stat_monitor` from [the releases page on GitHub](https://github.com/Percona/pg_stat_monitor/releases) or using git:
```
git clone git://github.com/Percona/pg_stat_monitor.git
```
Compile and install the extension
```
cd pg_stat_monitor
make USE_PGXS=1
make USE_PGXS=1 install
```
## Setup
You can enable `pg_stat_monitor` when your `postgresql` instance is not running.
`pg_stat_monitor` needs to be loaded at the start time. The extension requires additional shared memory; therefore, add the `pg_stat_monitor` value for the `shared_preload_libraries` parameter and restart the `postgresql` instance.
Use the [ALTER SYSTEM](https://www.postgresql.org/docs/current/sql-altersystem.html)command from `psql` terminal to modify the `shared_preload_libraries` parameter.
```sql
ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_monitor';
```
> **NOTE**: If you’ve added other modules to the `shared_preload_libraries` parameter (for example, `pg_stat_statements`), list all of them separated by commas for the `ALTER SYSTEM` command.
>
>:warning: For PostgreSQL 13 and earlier versions,`pg_stat_monitor` **must** follow `pg_stat_statements`. For example, `ALTER SYSTEM SET shared_preload_libraries = 'foo, pg_stat_statements, pg_stat_monitor'`.
>
>In PostgreSQL 14, you can specify `pg_stat_statements` and `pg_stat_monitor` in any order. However, due to the extensions' architecture, if both `pg_stat_statements` and `pg_stat_monitor` are loaded, only the last listed extension captures utility queries, CREATE TABLE, Analyze, etc. The first listed extension captures most common queries like SELECT, UPDATE, INSERT, but does not capture utility queries.
>
>Thus, to collect the whole statistics with pg_stat_monitor, we recommend to specify the extensions as follows: ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements, pg_stat_monitor'.
Start or restart the `postgresql` instance to apply the changes.
* On Debian and Ubuntu:
```sh
sudo systemctl restart postgresql.service
```
* On Red Hat Enterprise Linux and CentOS:
```sh
sudo systemctl restart postgresql-13
```
Create the extension using the [CREATE EXTENSION](https://www.postgresql.org/docs/current/sql-createextension.html) command. Using this command requires the privileges of a superuser or a database owner. Connect to `psql` as a superuser for a database and run the following command:
```sql
CREATE EXTENSION pg_stat_monitor;
```
This allows you to see the stats collected by `pg_stat_monitor`.
By default, `pg_stat_monitor` is created for the `postgres` database. To access the statistics from other databases, you need to create the extension for every database.
```
-- Select some of the query information, like client_ip, username and application_name etc.
postgres=# SELECT application_name, userid AS user_name, datname AS database_name, substr(query,0, 50) AS query, calls, client_ip
FROM pg_stat_monitor;
application_name | user_name | database_name | query | calls | client_ip
------------------+-----------+---------------+---------------------------------------------------+-------+-----------
psql | vagrant | postgres | SELECT application_name, userid::regrole AS user_ | 1 | 127.0.0.1
psql | vagrant | postgres | SELECT application_name, userid AS user_name, dat | 3 | 127.0.0.1
psql | vagrant | postgres | SELECT application_name, userid AS user_name, dat | 1 | 127.0.0.1
psql | vagrant | postgres | SELECT application_name, userid AS user_name, dat | 8 | 127.0.0.1
psql | vagrant | postgres | SELECT bucket, substr(query,$1, $2) AS query, cmd | 1 | 127.0.0.1
(5 rows)
```
To learn more about `pg_stat_monitor` features and usage, see [User Guide](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md). To view all other data elements provided by `pg_stat_monitor`, please see the [`pg_stat_monitor` view reference](REREFENCE.md).
## Configuration
You can find the configuration parameters of the `pg_stat_monitor` extension in the `pg_stat_monitor_settings` view. To change the default configuration, specify new values for the desired parameters using the GUC (Grant Unified Configuration) system. To learn more, refer to the [Configuration](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md#configuration) section of the user guide.
## Remove `pg_stat_monitor`
To uninstall `pg_stat_monitor`, do the following:
1. Disable statistics collection. Establish the `psql` session and run the following command :
```sql
ALTER SYSTEM SET pg_stat_monitor.pgsm_enable = 0;
```
2. Drop `pg_stat_monitor` extension:
```sql
DROP EXTENSION pg_stat_monitor;
```
3. Remove `pg_stat_monitor` from the `shared_preload_libraries` configuration parameter:
```sql
ALTER SYSTEM SET shared_preload_libraries = '';
```
!!! important
If the `shared_preload_libraries` parameter includes other modules, specify them all for the `ALTER SYSTEM SET` command to keep using them.
4. Restart the `postgresql` instance to apply the changes. The following command restarts PostgreSQL 13. Replace the version value with the one you are using.
* On Debian and Ubuntu:
```sh
sudo systemctl restart postgresql.service
```
* On Red Hat Enterprise Linux and CentOS:
```sh
sudo systemctl restart postgresql-13
```

12
requirements-doc.txt
View File

@ -1,12 +0,0 @@
mkdocs
mkdocs-macros-plugin
mkdocs-exclude
markdown-include
mkdocs-material
mkdocs-with-pdf
mkdocs-git-revision-date-plugin
mkdocs-material-extensions
mkdocs-bootstrap-tables-plugin
mkdocs-section-index
mkdocs-htmlproofer-plugin
mike