Skip to content

Commit 58597ed

Browse files
michaelpqmichaelpq
committed
doc: Simplify description of functions for pg_walinspect
As introduced in 2258e76, the docs were hard to parse: - The examples used listed a lot of long records, bloating the output. These are switched to show less records with the expanded format, similarly to pageinspect. - The function descriptions listed all the OUT parameters, producing long lines. This is updated so as only the input parameters are documented, clarifying the whole. - Remove one example on pg_get_wal_stats() when per_record is set to true, which is not really necessary once we know the output produced, and the behavior of the parameter is documented. While on it, fix a few grammar mistakes and simplify a couple of sentences. Author: Bharath Rupireddy Discussion: https://postgr.es/m/CALj2ACVGcUpziGgQrcT-1G3dHWQQfWjYBu1YQ2ypv9y86dgogg@mail.gmail.com Backpatch-through: 15
1 parent f1821b5 commit 58597ed

File tree

1 file changed

+54
-127
lines changed

1 file changed

+54
-127
lines changed

‎doc/src/sgml/pgwalinspect.sgml

Lines changed: 54 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
The <filename>pg_walinspect</filename> module provides SQL functions that
1212
allow you to inspect the contents of write-ahead log of
1313
a running <productname>PostgreSQL</productname> database cluster at a low
14-
level, which is useful for debugging or analytical or reporting or
14+
level, which is useful for debugging, analytical, reporting or
1515
educational purposes. It is similar to <xref linkend="pgwaldump"/>, but
1616
accessible through SQL rather than a separate utility.
1717
</para>
@@ -53,47 +53,39 @@
5353
<variablelist>
5454
<varlistentry id="pgwalinspect-funcs-pg-get-wal-record-info">
5555
<term>
56-
<function>
57-
pg_get_wal_record_info(in_lsn pg_lsn,
58-
start_lsn OUT pg_lsn,
59-
end_lsn OUT pg_lsn,
60-
prev_lsn OUT pg_lsn,
61-
xid OUT xid,
62-
resource_manager OUT text,
63-
record_type OUT text,
64-
record_length OUT int4,
65-
main_data_length OUT int4,
66-
fpi_length OUT int4,
67-
description OUT text,
68-
block_ref OUT text)
69-
</function>
56+
<function>pg_get_wal_record_info(in_lsn pg_lsn) returns record</function>
7057
</term>
7158

7259
<listitem>
7360
<para>
7461
Gets WAL record information of a given LSN. If the given LSN isn't
7562
at the start of a WAL record, it gives the information of the next
7663
available valid WAL record; or an error if no such record is found.
64+
For example, usage of the function is as
65+
follows:
66+
<screen>
67+
postgres=# SELECT * FROM pg_get_wal_record_info('0/1E826E98');
68+
-[ RECORD 1 ]----+----------------------------------------------------
69+
start_lsn | 0/1E826F20
70+
end_lsn | 0/1E826F60
71+
prev_lsn | 0/1E826C80
72+
xid | 0
73+
resource_manager | Heap2
74+
record_type | PRUNE
75+
record_length | 58
76+
main_data_length | 8
77+
fpi_length | 0
78+
description | snapshotConflictHorizon 33748 nredirected 0 ndead 2
79+
block_ref | blkref #0: rel 1663/5/60221 fork main blk 2
80+
</screen>
7781
</para>
7882
</listitem>
7983
</varlistentry>
8084

8185
<varlistentry id="pgwalinspect-funcs-pg-get-wal-records-info">
8286
<term>
8387
<function>
84-
pg_get_wal_records_info(start_lsn pg_lsn,
85-
end_lsn pg_lsn,
86-
start_lsn OUT pg_lsn,
87-
end_lsn OUT pg_lsn,
88-
prev_lsn OUT pg_lsn,
89-
xid OUT xid,
90-
resource_manager OUT text,
91-
record_type OUT text,
92-
record_length OUT int4,
93-
main_data_length OUT int4,
94-
fpi_length OUT int4,
95-
description OUT text,
96-
block_ref OUT text)
88+
pg_get_wal_records_info(start_lsn pg_lsn, end_lsn pg_lsn)
9789
returns setof record
9890
</function>
9991
</term>
@@ -104,25 +96,21 @@
10496
<replaceable>start_lsn</replaceable> and <replaceable>end_lsn</replaceable>.
10597
Returns one row per WAL record. If <replaceable>start_lsn</replaceable>
10698
or <replaceable>end_lsn</replaceable> are not yet available, the
107-
function will raise an error. For example, usage of the function is as
108-
follows:
99+
function will raise an error. For example:
109100
<screen>
110-
postgres=# select start_lsn, end_lsn, prev_lsn, xid, resource_manager, record_type, record_length, main_data_length, fpi_length, description from pg_get_wal_records_info('0/14F9A30', '0/15011D7');
111-
start_lsn | end_lsn | prev_lsn | xid | resource_manager | record_type | record_length | main_data_length | fpi_length | description
112-
-----------+-----------+-----------+-----+------------------+--------------+---------------+------------------+------------+---------------------
113-
0/14FA118 | 0/14FB4B0 | 0/14F9958 | 725 | Btree | INSERT_LEAF | 5013 | 2 | 4960 | off 246
114-
0/14FB4B0 | 0/14FD050 | 0/14FA118 | 725 | Btree | INSERT_LEAF | 7045 | 2 | 6992 | off 130
115-
0/14FD050 | 0/14FD0A8 | 0/14FB4B0 | 725 | Heap2 | MULTI_INSERT | 85 | 6 | 0 | 1 tuples flags 0x02
116-
0/14FD0A8 | 0/14FD0F0 | 0/14FD050 | 725 | Btree | INSERT_LEAF | 72 | 2 | 0 | off 155
117-
0/14FD0F0 | 0/14FD138 | 0/14FD0A8 | 725 | Btree | INSERT_LEAF | 72 | 2 | 0 | off 134
118-
0/14FD138 | 0/14FD210 | 0/14FD0F0 | 725 | Heap | INSERT | 211 | 3 | 0 | off 11 flags 0x00
119-
0/14FD210 | 0/14FD250 | 0/14FD138 | 725 | Btree | INSERT_LEAF | 64 | 2 | 0 | off 246
120-
0/14FD250 | 0/14FF260 | 0/14FD210 | 725 | Btree | INSERT_LEAF | 8181 | 2 | 8128 | off 47
121-
0/14FF260 | 0/14FF2B8 | 0/14FD250 | 725 | Heap2 | MULTI_INSERT | 85 | 6 | 0 | 1 tuples flags 0x02
122-
0/14FF2B8 | 0/14FF300 | 0/14FF260 | 725 | Btree | INSERT_LEAF | 72 | 2 | 0 | off 155
123-
0/14FF300 | 0/15008D8 | 0/14FF2B8 | 725 | Btree | INSERT_LEAF | 5565 | 2 | 5512 | off 106
124-
0/15008D8 | 0/1500C48 | 0/14FF300 | 725 | Heap | INSERT | 874 | 3 | 820 | off 2 flags 0x01
125-
(12 rows)
101+
postgres=# SELECT * FROM pg_get_wal_records_info('0/1E913618', '0/1E913740') LIMIT 1;
102+
-[ RECORD 1 ]----+--------------------------------------------------------------
103+
start_lsn | 0/1E913618
104+
end_lsn | 0/1E913650
105+
prev_lsn | 0/1E9135A0
106+
xid | 0
107+
resource_manager | Standby
108+
record_type | RUNNING_XACTS
109+
record_length | 50
110+
main_data_length | 24
111+
fpi_length | 0
112+
description | nextXid 33775 latestCompletedXid 33774 oldestRunningXid 33775
113+
block_ref |
126114
</screen>
127115
</para>
128116
</listitem>
@@ -131,25 +119,14 @@ postgres=# select start_lsn, end_lsn, prev_lsn, xid, resource_manager, record_ty
131119
<varlistentry id="pgwalinspect-funcs-pg-get-wal-records-info-till-end-of-wal">
132120
<term>
133121
<function>
134-
pg_get_wal_records_info_till_end_of_wal(start_lsn pg_lsn,
135-
start_lsn OUT pg_lsn,
136-
end_lsn OUT pg_lsn,
137-
prev_lsn OUT pg_lsn,
138-
xid OUT xid,
139-
resource_manager OUT text,
140-
record_type OUT text,
141-
record_length OUT int4,
142-
main_data_length OUT int4,
143-
fpi_length OUT int4,
144-
description OUT text,
145-
block_ref OUT text)
122+
pg_get_wal_records_info_till_end_of_wal(start_lsn pg_lsn)
146123
returns setof record
147124
</function>
148125
</term>
149126

150127
<listitem>
151128
<para>
152-
This function is same as <function>pg_get_wal_records_info()</function>
129+
This function is the same as <function>pg_get_wal_records_info()</function>,
153130
except that it gets information of all the valid WAL records from
154131
<replaceable>start_lsn</replaceable> till the end of WAL.
155132
</para>
@@ -159,18 +136,7 @@ postgres=# select start_lsn, end_lsn, prev_lsn, xid, resource_manager, record_ty
159136
<varlistentry id="pgwalinspect-funcs-pg-get-wal-stats">
160137
<term>
161138
<function>
162-
pg_get_wal_stats(start_lsn pg_lsn,
163-
end_lsn pg_lsn,
164-
per_record boolean DEFAULT false,
165-
"resource_manager/record_type" OUT text,
166-
count OUT int8,
167-
count_percentage OUT float8,
168-
record_length OUT int8,
169-
record_length_percentage OUT float8,
170-
fpi_length OUT int8,
171-
fpi_length_percentage OUT float8,
172-
combined_size OUT int8,
173-
combined_size_percentage OUT float8)
139+
pg_get_wal_stats(start_lsn pg_lsn, end_lsn pg_lsn, per_record boolean DEFAULT false)
174140
returns setof record
175141
</function>
176142
</term>
@@ -185,50 +151,21 @@ postgres=# select start_lsn, end_lsn, prev_lsn, xid, resource_manager, record_ty
185151
it returns one row per <replaceable>record_type</replaceable>.
186152
If <replaceable>start_lsn</replaceable>
187153
or <replaceable>end_lsn</replaceable> are not yet available, the
188-
function will raise an error. For example, usage of the function is as
189-
follows:
190-
<screen>
191-
postgres=# select * from pg_get_wal_stats('0/12FBA30', '0/15011D7') where count > 0;
192-
resource_manager/record_type | count | count_percentage | record_size | record_size_percentage | fpi_size | fpi_size_percentage | combined_size | combined_size_percentage
193-
------------------------------+-------+------------------+-------------+------------------------+----------+---------------------+---------------+--------------------------
194-
XLOG | 10 | 0.10871929 | 796 | 0.052369177 | 352 | 0.061031006 | 1148 | 0.054751817
195-
Transaction | 187 | 2.0330508 | 62773 | 4.1298623 | 0 | 0 | 62773 | 2.9938467
196-
Storage | 13 | 0.14133507 | 546 | 0.035921574 | 0 | 0 | 546 | 0.0260405
197-
Database | 2 | 0.021743858 | 84 | 0.005526396 | 0 | 0 | 84 | 0.0040062307
198-
Standby | 218 | 2.3700805 | 15908 | 1.0465941 | 0 | 0 | 15908 | 0.75870377
199-
Heap2 | 1897 | 20.624048 | 383916 | 25.257998 | 364472 | 63.193447 | 748388 | 35.693035
200-
Heap | 1318 | 14.329202 | 621390 | 40.88151 | 139660 | 24.214746 | 761050 | 36.29693
201-
Btree | 5553 | 60.37182 | 434565 | 28.590216 | 72272 | 12.530776 | 506837 | 24.17269
202-
(8 rows)
203-
</screen>
204-
205-
With <replaceable>per_record</replaceable> passed as <literal>true</literal>:
206-
154+
function will raise an error. For example:
207155
<screen>
208-
postgres=# select * from pg_get_wal_stats('0/14AFC30', '0/15011D7', true) where count > 0;
209-
resource_manager/record_type | count | count_percentage | record_size | record_size_percentage | fpi_size | fpi_size_percentage | combined_size | combined_size_percentage
210-
------------------------------+-------+------------------+-------------+------------------------+----------+---------------------+---------------+--------------------------
211-
XLOG/CHECKPOINT_SHUTDOWN | 1 | 0.32894737 | 114 | 0.22891566 | 0 | 0 | 114 | 0.03534489
212-
XLOG/CHECKPOINT_ONLINE | 4 | 1.3157895 | 456 | 0.91566265 | 0 | 0 | 456 | 0.14137957
213-
XLOG/NEXTOID | 1 | 0.32894737 | 30 | 0.060240965 | 0 | 0 | 30 | 0.009301287
214-
Transaction/COMMIT | 9 | 2.9605262 | 1173 | 2.3554218 | 0 | 0 | 1173 | 0.36368033
215-
Storage/CREATE | 1 | 0.32894737 | 42 | 0.084337346 | 0 | 0 | 42 | 0.0130218025
216-
Database/CREATE_FILE_COPY | 2 | 0.65789473 | 84 | 0.16867469 | 0 | 0 | 84 | 0.026043605
217-
Standby/RUNNING_XACTS | 6 | 1.9736842 | 316 | 0.6345382 | 0 | 0 | 316 | 0.09797356
218-
Standby/INVALIDATIONS | 45 | 14.802631 | 4018 | 8.068274 | 0 | 0 | 4018 | 1.2457525
219-
Heap2/PRUNE | 4 | 1.3157895 | 270 | 0.5421687 | 0 | 0 | 270 | 0.08371159
220-
Heap2/FREEZE_PAGE | 27 | 8.881579 | 20904 | 41.975903 | 0 | 0 | 20904 | 6.481137
221-
Heap2/VISIBLE | 29 | 9.539474 | 1756 | 3.5261045 | 73728 | 27.032736 | 75484 | 23.403278
222-
Heap2/MULTI_INSERT | 13 | 4.2763157 | 1049 | 2.1064258 | 12216 | 4.479057 | 13265 | 4.112719
223-
Heap/INSERT | 19 | 6.25 | 2324 | 4.6666665 | 43884 | 16.090284 | 46208 | 14.326463
224-
Heap/UPDATE | 7 | 2.3026316 | 511 | 1.0261045 | 54340 | 19.924028 | 54851 | 17.006165
225-
Heap/HOT_UPDATE | 11 | 3.618421 | 1134 | 2.2771084 | 468 | 0.17159452 | 1602 | 0.49668875
226-
Heap/LOCK | 8 | 2.631579 | 432 | 0.8674699 | 0 | 0 | 432 | 0.13393854
227-
Heap/INPLACE | 45 | 14.802631 | 9123 | 18.319277 | 16076 | 5.894345 | 25199 | 7.8127713
228-
Heap/UPDATE+INIT | 1 | 0.32894737 | 817 | 1.6405623 | 0 | 0 | 817 | 0.25330505
229-
Btree/INSERT_LEAF | 70 | 23.026316 | 5183 | 10.407631 | 72024 | 26.407955 | 77207 | 23.937483
230-
Btree/DEDUP | 1 | 0.32894737 | 64 | 0.12851405 | 0 | 0 | 64 | 0.019842746
231-
(20 rows)
156+
postgres=# SELECT * FROM pg_get_wal_stats('0/1E847D00', '0/1E84F500')
157+
WHERE count > 0 LIMIT 1 AND
158+
"resource_manager/record_type" = 'Transaction';
159+
-[ RECORD 1 ]----------------+-------------------
160+
resource_manager/record_type | Transaction
161+
count | 2
162+
count_percentage | 8
163+
record_size | 875
164+
record_size_percentage | 41.23468426013195
165+
fpi_size | 0
166+
fpi_size_percentage | 0
167+
combined_size | 875
168+
combined_size_percentage | 2.8634072910530795
232169
</screen>
233170
</para>
234171
</listitem>
@@ -237,25 +174,15 @@ postgres=# select * from pg_get_wal_stats('0/14AFC30', '0/15011D7', true) where
237174
<varlistentry id="pgwalinspect-funcs-pg-get-wal-stats-till-end-of-wal">
238175
<term>
239176
<function>
240-
pg_get_wal_stats_till_end_of_wal(start_lsn pg_lsn,
241-
per_record boolean DEFAULT false,
242-
"resource_manager/record_type" OUT text,
243-
count OUT int8,
244-
count_percentage OUT float8,
245-
record_length OUT int8,
246-
record_length_percentage OUT float8,
247-
fpi_length OUT int8,
248-
fpi_length_percentage OUT float8,
249-
combined_size OUT int8,
250-
combined_size_percentage OUT float8)
177+
pg_get_wal_stats_till_end_of_wal(start_lsn pg_lsn, end_lsn pg_lsn, per_record boolean DEFAULT false)
251178
returns setof record
252179
</function>
253180
</term>
254181

255182
<listitem>
256183
<para>
257-
This function is same as <function>pg_get_wal_stats()</function> except
258-
that it gets statistics of all the valid WAL records from
184+
This function is the same as <function>pg_get_wal_stats()</function>,
185+
except that it gets statistics of all the valid WAL records from
259186
<replaceable>start_lsn</replaceable> till end of WAL.
260187
</para>
261188
</listitem>

0 commit comments

Comments
 (0)