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

Merge pull request #64 from nastena1606/Docs-review 

pg_stat_monitor doc review
pull/65/head^2^2
Ibrar Ahmed 2020-11-26 21:48:13 +05:00 committed by GitHub
parent f8a9bcf9f2 55e3d2397c
commit 75bafcb590
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 61 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
README.md
View File

@ -1,5 +1,11 @@
## What is pg_stat_monitor?
The pg_stat_monitor is the statistics collection tool based on PostgreSQL's contrib module ``pg_stat_statements``. PostgreSQL’s pg_stat_statements provides the basic statistics, which is sometimes not enough. The major shortcoming in pg_stat_statements is that it accumulates all the queries and their statistics and does not provide aggregated statistics nor histogram information. In this case, a user needs to calculate the aggregate which is quite expensive. ``pg_stat_monitor`` is developed on the basis of pg_stat_statements as its more advanced replacement. It provides all the features of pg_stat_statements plus its own feature set.
The ``pg_stat_monitor`` is the statistics collection tool based on PostgreSQL's contrib module ``pg_stat_statements``. PostgreSQL’s pg_stat_statements provides the basic statistics, which is sometimes not enough. The major shortcoming in pg_stat_statements is that it accumulates all the queries and their statistics and does not provide aggregated statistics nor histogram information. In this case, a user needs to calculate the aggregate which is quite expensive.
``pg_stat_monitor`` is developed on the basis of pg_stat_statements as its more advanced replacement. It provides all the features of pg_stat_statements plus its own feature set.
### How pg_stat_monitor works?
pg_stat_monitor accumulates the information in the form of buckets. All the aggregated information is bucket based. The size of a bucket and the number of buckets should be configured using GUC (Grand Unified Configuration). When a bucket time elapses, pg_stat_monitor resets all the statistics and switches to the next bucket. After the last bucket elapses, pg_stat_monitor goes back to the first bucket. All the data on the first bucket will vanish; therefore, users must read the buckets before that to not lose the data.
## Documentation
1. [Supported PostgreSQL Versions](#supported-postgresql-versions)
@ -8,7 +14,8 @@ The pg_stat_monitor is the statistics collection tool based on PostgreSQL's cont
4. [User Guide](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md)
6. [Release Notes](https://github.com/percona/pg_stat_monitor/blob/master/docs/RELEASE_NOTES.md)
7. [License](https://github.com/percona/pg_stat_monitor/blob/master/LICENSE)
8. [Copyright Notice](#copyright-notice)
8. [Submitting Bug Reports](#submitting-bug-reports)
9. [Copyright Notice](#copyright-notice)
## Supported PostgreSQL Versions
The ``pg_stat_monitor`` should work on the latest version of PostgreSQL but is only tested with these PostgreSQL versions:
@ -25,14 +32,16 @@ The ``pg_stat_monitor`` should work on the latest version of PostgreSQL but is o
| Percona Distribution | Version 13 | :heavy_check_mark: |
## Installation
pg_stat_monitor is supplied as part of Percona Distribution for PostgreSQL. The rpm/deb packages are available from Percona repositories. Refer to [Percona Documentation](https://www.percona.com/doc/postgresql/LATEST/installing.html) for installation instructions.
``pg_stat_monitor`` is supplied as part of Percona Distribution for PostgreSQL. The rpm/deb packages are available from Percona repositories. Refer to [Percona Documentation](https://www.percona.com/doc/postgresql/LATEST/installing.html) for installation instructions.
The source code of latest release of ``pg_stat_monitor`` can be downloaded from [this GitHub page](https://github.com/Percona/pg_stat_monitor/releases) or it can be downloaded using the git:
### Installing from source code
You can download the source code of the latest release of ``pg_stat_monitor`` from [this GitHub page](https://github.com/Percona/pg_stat_monitor/releases) or using git:
```sh
git clone git://github.com/Percona/pg_stat_monitor.git
```
Compile and Install the extension
Compile and install the extension
```sh
cd pg_stat_monitor
make USE_PGXS=1
@ -40,7 +49,9 @@ make USE_PGXS=1 install
```
## Setup
``pg_stat_monitor`` cannot be installed in your running PostgreSQL instance. It should be set in the ``postgresql.conf`` file.
``pg_stat_monitor`` cannot be enabled in your running PostgreSQL instance. ``pg_stat_monitor`` needs to be loaded at the start time. This requires adding the ``pg_stat_monitor`` extension for the ``shared_preload_libraries`` parameter and restarting the PostgreSQL instance.
You can set the ``pg_stat_monitor`` extension in the ``postgresql.conf`` file.
```
# - Shared Library Preloading -
@ -50,9 +61,8 @@ shared_preload_libraries = 'pg_stat_monitor' # (change requires restart)
#session_preload_libraries = ''
```
Or you can do from `psql` terminal using the ``alter system`` command.
Or you can set it from `psql` terminal using the ``alter system`` command.
``pg_stat_monitor`` needs to be loaded at the start time. This requires adding the ``pg_stat_monitor`` extension for the ``shared_preload_libraries`` parameter and restart the PostgreSQL instance.
```sql
ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_monitor';
ALTER SYSTEM
@ -102,5 +112,30 @@ SELECT decode_error_level(elevel) AS elevel, sqlcode, query, message FROM pg_st
```
To learn more about ``pg_stat_monitor`` configuration and usage, see [User Guide](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md).
## Submitting Bug Reports
If you found a bug in ``pg_stat_statements``, please submit the report to the [Jira issue tracker](https://jira.percona.com/projects/PG/issues)
Start by searching the open tickets for a similar report. If you find that someone else has already reported your issue, then you can upvote that report to increase its visibility.
If there is no existing report, submit your report following these steps:
Sign in to [Jira issue tracker](https://jira.percona.com/projects/PG/issues). You will need to create an account if you do not have one.
In the *Summary*, *Description*, *Steps To Reproduce*, *Affects Version* fields describe the problem you have detected.
As a general rule of thumb, try to create bug reports that are:
- Reproducible: describe the steps to reproduce the problem.
- Specific: include the version of Percona Backup for MongoDB, your environment, and so on.
- Unique: check if there already exists a JIRA ticket to describe the problem.
- Scoped to a Single Bug: only report one bug in one JIRA ticket.
## Copyright Notice
Copyright (c) 2006 - 2020, Percona LLC.

30
docs/USER_GUIDE.md
View File

@ -1,6 +1,10 @@
## User Guide
# User Guide
Create the extension using the ``CREATE EXTENSION`` command.
This document describes the configuration, key features and usage of ``pg_stat_monitor`` extension and compares it with ``pg_stat_statements``.
For how to install and set up ``pg_stat_monitor``, see [README](https://github.com/percona/pg_stat_monitor/blob/master/README.md).
After you've installed and enabled ``pg_stat_monitor``, create the ``pg_stat_monitor`` extension using the ``CREATE EXTENSION`` command.
```sql
CREATE EXTENSION pg_stat_monitor;
@ -27,7 +31,7 @@ SELECT * FROM pg_stat_monitor_settings;
```
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``).
The table below shows set up options for each configuration parameter and whether the server restart is required to apply its value:
The table below shows set up 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
@ -59,9 +63,10 @@ The table below shows set up options for each configuration parameter and whethe
### Usage
pg_stat_monitor extension contains a view called pg_stat_monitor, which contains all the monitoring information. Following is the list of columns in pg_stat_monitor.
pg_stat_monitor extension contains a view called pg_stat_monitor, which contains all the monitoring information. Find the list of columns in pg_stat_monitor view in the following table. The table also shows whether a particular column is available in pg_stat_statements.
|      Column        |           Type           | pg_stat_monitor      | pg_stat_statments
|      Column        |           Type           | pg_stat_monitor      | pg_stat_statements
|--------------------|--------------------------|----------------------|------------------
 bucket              | integer                  | :heavy_check_mark:  | :x:
 bucket_start_time   | timestamp with time zone | :heavy_check_mark:  | :x:
@ -105,10 +110,11 @@ pg_stat_monitor extension contains a view called pg_stat_monitor, which contains
 cpu_user_time       | double precision         | :heavy_check_mark:  | :x:
 cpu_sys_time        | double precision         | :heavy_check_mark:  | :x:
Here are some key features of pg_stat_monitor.
The following are some key features of pg_stat_monitor and usage examples.
#### Buckets
pg_stat_monitor collects and aggregates data on a bucket basis. The size of a bucket and the number of buckets should be configured using GUC (Grand Unified Configuration). When a bucket time elapses, pg_stat_monitor resets all the statistics and switches to the next bucket. After the last bucket elapses, pg_stat_monitor goes back to the first bucket. All the data on the first bucket will vanish; therefore, users must read the buckets before that to not lose the data.
**`bucket`**: Accumulates the statistics per bucket. All the information and aggregate reset for each bucket. The bucket will be a number showing the number of buckets for which this record belongs.
@ -126,7 +132,7 @@ SELECT bucket, bucket_start_time, query FROM pg_stat_monitor;
#### Query Information
**`userid`**: An ID of the user to whom that query belongs. pg_stat_monitor is used to collect queries from all the users; therefore, `userid` is used to segregate the queries based on different users.
**`userid`**: An ID of the user to whom that query belongs. pg_stat_monitor collects queries from all the users and uses the `userid` to segregate the queries based on different users.
**`dbid`**: The database ID of the query. pg_stat_monitor accumulates queries from all the databases; therefore, this column is used to identify the database.
@ -137,7 +143,7 @@ SELECT bucket, bucket_start_time, query FROM pg_stat_monitor;
**`calls`**: Number of calls of that particular query.
##### Example 1: Shows the userid, dbid, unique queryid hash, query, and the total number of calls or that query.
##### Example 1: Shows the userid, dbid, unique queryid hash, query, and the total number of calls of that query.
```sql
SELECT userid,  dbid, queryid, substr(query,0, 50) AS query, calls FROM pg_stat_monitor;
 userid | dbid  |     queryid      |                       query                       | calls
@ -163,7 +169,7 @@ SELECT userid,  dbid, queryid, substr(query,0, 50) AS query, calls FROM pg_stat
(18 rows)
```
##### Example 2: Shows the different usernames for the query.
##### Example 2: Shows different usernames for the query.
```
SELECT userid::regrole, datname, substr(query,0, 50) AS query, calls from pg_stat_monitor, pg_database WHERE dbid = oid;
@ -177,7 +183,7 @@ SELECT userid::regrole, datname, substr(query,0, 50) AS query, calls from pg_sta
(5 rows)
```
##### Example 3: Shows the different database involved in the queries.
##### Example 3: Shows the different databases involved in the queries.
```
SELECT userid::regrole, datname, substr(query,0, 50) as query, calls from pg_stat_monitor, pg_database WHERE dbid = oid;
@ -213,7 +219,7 @@ SELECT application_name, query FROM pg_stat_monitor;
#### Error Messages / Error Codes and Error Level
**`elevel`**, **`sqlcode`**,**`message`**,: error level / sql code and  log/warning/error message
**`elevel`**, **`sqlcode`**,**`message`**,: error level / sql code and  log/warning/ error message
```sql
SELECT substr(query,0,50) AS query, decode_error_level(elevel) AS elevel,sqlcode, calls, substr(message,0,50) message