Skip to content

Commit 1597439

Browse files
author
Oleg Tselebrovskiy
committed
Update README to include information about new *_extended views
Also fix some typos/reword some sentences
1 parent 7cc9d5b commit 1597439

File tree

1 file changed

+107
-28
lines changed

1 file changed

+107
-28
lines changed

‎README.md‎

Lines changed: 107 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,13 @@ Introduction
99

1010
PostgreSQL provides information about current wait event of particular
1111
process. However, in order to gather descriptive statistics of server
12-
behavior user have to sample current wait event multiple times.
12+
behavior users have to sample current wait events multiple times.
1313
`pg_wait_sampling` is an extension for collecting sampling statistics of wait
1414
events.
1515

1616
The module must be loaded by adding `pg_wait_sampling` to
1717
`shared_preload_libraries` in postgresql.conf, because it requires additional
18-
shared memory and launches background worker. This means that a server restart
18+
shared memory and launches a background worker. This means that a server restart
1919
is needed to add or remove the module.
2020

2121
When used with `pg_stat_statements` it is recommended to put `pg_stat_statements`
@@ -25,17 +25,16 @@ utility statements are not rewritten by the former.
2525
When `pg_wait_sampling` is enabled, it collects two kinds of statistics.
2626

2727
* History of waits events. It's implemented as in-memory ring buffer where
28-
samples of each process wait events are written with given (configurable)
28+
samples of each process' wait events are written with given (configurable)
2929
period. Therefore, for each running process user can see some number of
30-
recent samples depending on history size (configurable). Assuming there is
31-
a client who periodically read this history and dump it somewhere, user
32-
can have continuous history.
33-
* Waits profile. It's implemented as in-memory hash table where count
34-
of samples are accumulated per each process and each wait event
35-
(and each query with `pg_stat_statements`). This hash
36-
table can be reset by user request. Assuming there is a client who
37-
periodically dumps profile and resets it, user can have statistics of
38-
intensivity of wait events among time.
30+
recent samples depending on history size (configurable). Assuming there is
31+
a client who periodically reads this history and dumps it somewhere, user
32+
can have continuous history of wait events.
33+
* Waits profile. It's implemented as in-memory hash table where samples
34+
are accumulated per each wait event and can be divided by process,
35+
query and other dimensions. This hash table can be reset by user request.
36+
Assuming there is a client who periodically dumps profile and resets it,
37+
user can have statistics of wait events over time.
3938

4039
In combination with `pg_stat_statements` this extension can also provide
4140
per query statistics.
@@ -66,10 +65,10 @@ Manual build
6665
higher. Before build and install you should ensure following:
6766

6867
* PostgreSQL version is 13 or higher.
69-
* You have development package of PostgreSQL installed or you built
68+
* You have development package of PostgreSQL installed or you have built
7069
PostgreSQL from source.
7170
* Your PATH variable is configured so that `pg_config` command available, or
72-
set PG_CONFIG variable.
71+
PG_CONFIG variable is set.
7372

7473
Typical installation procedure may look like this:
7574

@@ -98,9 +97,9 @@ Usage
9897
`pg_wait_sampling` interacts with user by set of views and functions.
9998

10099
`pg_wait_sampling_current` view – information about current wait events for
101-
all processed including background workers.
100+
all processes including background workers.
102101

103-
| Column name | Column type | Description |
102+
| Column name | Column type | Description |
104103
| ----------- | ----------- | ----------------------- |
105104
| pid | int4 | Id of process |
106105
| event_type | text | Name of wait event type |
@@ -110,41 +109,108 @@ all processed including background workers.
110109
`pg_wait_sampling_get_current(pid int4)` returns the same table for single given
111110
process.
112111

112+
`pg_wait_sampling_current_extended` view – information about current wait events for
113+
all processes including background workers. Structure of this view can be changed
114+
between verions.
115+
116+
| Column name | Column type | Description |
117+
| ------------------- | ----------- | --------------------------- |
118+
| pid | int4 | Id of process |
119+
| event_type | text | Name of wait event type |
120+
| event | text | Name of wait event |
121+
| queryid | int8 | Id of query |
122+
| role_id | int4 | Id of role |
123+
| database_id | int4 | Id of database |
124+
| parallel_leader_pid | int4 | Id of parallel query leader |
125+
| backend_type | text | Name of backend type |
126+
| backend_state | text | Name of backend state |
127+
| proc_start | timestamptz | Timestamp of process start |
128+
| client_addr | text | Client address |
129+
| client_hostname | text | Client hostname |
130+
| appname | text | Application name |
131+
132+
`pg_wait_sampling_get_current_extended(pid int4)` returns the same table for single given
133+
process.
134+
113135
`pg_wait_sampling_history` view – history of wait events obtained by sampling into
114136
in-memory ring buffer.
115137

116-
| Column name | Column type | Description |
138+
| Column name | Column type | Description |
117139
| ----------- | ----------- | ----------------------- |
118140
| pid | int4 | Id of process |
119141
| ts | timestamptz | Sample timestamp |
120142
| event_type | text | Name of wait event type |
121143
| event | text | Name of wait event |
122144
| queryid | int8 | Id of query |
123145

146+
`pg_wait_sampling_history_extended` view – history of wait events obtained by
147+
sampling into in-memory ring buffer. Structure of this view can be changed
148+
between verions
149+
150+
| Column name | Column type | Description |
151+
| ------------------- | ----------- | --------------------------- |
152+
| pid | int4 | Id of process |
153+
| ts | timestamptz | Sample timestamp |
154+
| event_type | text | Name of wait event type |
155+
| event | text | Name of wait event |
156+
| queryid | int8 | Id of query |
157+
| role_id | int4 | Id of role |
158+
| database_id | int4 | Id of database |
159+
| parallel_leader_pid | int4 | Id of parallel query leader |
160+
| backend_type | text | Name of backend type |
161+
| backend_state | text | Name of backend state |
162+
| proc_start | timestamptz | Timestamp of process start |
163+
| client_addr | text | Client address |
164+
| client_hostname | text | Client hostname |
165+
| appname | text | Application name |
166+
124167
`pg_wait_sampling_profile` view – profile of wait events obtained by sampling into
125168
in-memory hash table.
126169

127-
| Column name | Column type | Description |
170+
| Column name | Column type | Description |
128171
| ----------- | ----------- | ----------------------- |
129172
| pid | int4 | Id of process |
130173
| event_type | text | Name of wait event type |
131174
| event | text | Name of wait event |
132175
| queryid | int8 | Id of query |
133-
| count | text | Count of samples |
176+
| count | int8 | Count of samples |
177+
178+
`pg_wait_sampling_profile_extended` view – history of wait events obtained by
179+
sampling into in-memory ring buffer. Structure of this view can be changed
180+
between verions
181+
182+
| Column name | Column type | Description |
183+
| ------------------- | ----------- | --------------------------- |
184+
| pid | int4 | Id of process |
185+
| event_type | text | Name of wait event type |
186+
| event | text | Name of wait event |
187+
| queryid | int8 | Id of query |
188+
| role_id | int4 | Id of role |
189+
| database_id | int4 | Id of database |
190+
| parallel_leader_pid | int4 | Id of parallel query leader |
191+
| backend_type | text | Name of backend type |
192+
| backend_state | text | Name of backend state |
193+
| proc_start | timestamptz | Timestamp of process start |
194+
| client_addr | text | Client address |
195+
| client_hostname | text | Client hostname |
196+
| appname | text | Application name |
197+
| count | int8 | Count of samples |
134198

135199
`pg_wait_sampling_reset_profile()` function resets the profile.
136200

137201
The work of wait event statistics collector worker is controlled by following
138202
GUCs.
139203

140-
| Parameter name | Data type | Description | Default value |
141-
|----------------------------------| --------- |---------------------------------------------|--------------:|
142-
| pg_wait_sampling.history_size | int4 | Size of history in-memory ring buffer | 5000 |
143-
| pg_wait_sampling.history_period | int4 | Period for history sampling in milliseconds | 10 |
144-
| pg_wait_sampling.profile_period | int4 | Period for profile sampling in milliseconds | 10 |
145-
| pg_wait_sampling.profile_pid | bool | Whether profile should be per pid | true |
146-
| pg_wait_sampling.profile_queries | enum | Whether profile should be per query | top |
147-
| pg_wait_sampling.sample_cpu | bool | Whether on CPU backends should be sampled | true |
204+
| Parameter name | Data type | Description | Default value |
205+
|-------------------------------------| --------- |---------------------------------------------|--------------:|
206+
| pg_wait_sampling.history_size | int4 | Size of history in-memory ring buffer | 5000 |
207+
| pg_wait_sampling.history_period | int4 | Period for history sampling in milliseconds | 10 |
208+
| pg_wait_sampling.profile_period | int4 | Period for profile sampling in milliseconds | 10 |
209+
| pg_wait_sampling.profile_pid | bool | Whether profile should be per pid | true |
210+
| pg_wait_sampling.profile_queries | enum | Whether profile should be per query | top |
211+
| pg_wait_sampling.sample_cpu | bool | Whether on CPU backends should be sampled | true |
212+
| pg_wait_sampling.history_dimensions | text | Additional columns in extended history view | 'none' |
213+
| pg_wait_sampling.profile_dimensions | text | Additional columns in extended profile view | 'none' |
148214

149215
If `pg_wait_sampling.profile_pid` is set to false, sampling profile wouldn't be
150216
collected in per-process manner. In this case the value of pid could would
@@ -158,6 +224,19 @@ If `pg_wait_sampling.sample_cpu` is set to true then processes that are not
158224
waiting on anything are also sampled. The wait event columns for such processes
159225
will be NULL.
160226

227+
`pg_wait_sampling.history_dimenstions` and `pg_wait_sampling.profile_dimensions`
228+
determine what additional columns will be sampled in `history/profile_extended`
229+
views. Possible values are `none`, `all`, `role_id`, `database_id`,
230+
`parallel_leader_pid`, `backend_type`, `backend_state`, `backend_start_time`,
231+
`client_addr`, `client_hostname`, `appname` and any combination of column names.
232+
`none` and `all` cannot be used together with any other values and must be used alone.
233+
234+
> [!WARNING]
235+
> Turning on any of the following columns: `backend_type`, `backend_state`,
236+
> `backend_start_time`, `client_addr`, `client_hostname`, `appname` will reduce
237+
> performance compared to sampling none of those due to the need to look into
238+
> BackendStatusTable. This is especially noticeable with PostgreSQL 13-16
239+
161240
Values of these GUC variables can be changed only in config file or with ALTER SYSTEM.
162241
Then you need to reload server's configuration (such as with pg_reload_conf function)
163242
for changes to take effect.
@@ -170,7 +249,7 @@ Contribution
170249
------------
171250

172251
Please, notice, that `pg_wait_sampling` is still under development and while
173-
it's stable and tested, it may contains some bugs. Don't hesitate to raise
252+
it's stable and tested, it may contain some bugs. Don't hesitate to raise
174253
[issues at github](https://github.com/postgrespro/pg_wait_sampling/issues) with
175254
your bug reports.
176255

0 commit comments

Comments
 (0)