1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
<!--
doc/src/sgml/ref/pgtesttiming.sgml
PostgreSQL documentation
-->
<refentry id="pgtesttiming">
<indexterm zone="pgtesttiming">
<primary>pg_test_timing</primary>
</indexterm>
<refmeta>
<refentrytitle><application>pg_test_timing</application></refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pg_test_timing</refname>
<refpurpose>measure timing overhead</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>pg_test_timing</command>
<arg rep="repeat"><replaceable>option</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<application>pg_test_timing</application> is a tool to measure the
timing overhead on your system and confirm that the system time never
moves backwards. It simply reads the system clock over and over again
as fast as it can for a specified length of time, and then prints
statistics about the observed differences in successive clock readings.
</para>
<para>
Smaller (but not zero) differences are better, since they imply both
more-precise clock hardware and less overhead to collect a clock reading.
Systems that are slow to collect timing data can give less accurate
<command>EXPLAIN ANALYZE</command> results.
</para>
<para>
This tool is also helpful to determine if
the <varname>track_io_timing</varname> configuration parameter is likely
to produce useful results.
</para>
</refsect1>
<refsect1>
<title>Options</title>
<para>
<application>pg_test_timing</application> accepts the following
command-line options:
<variablelist>
<varlistentry>
<term><option>-d <replaceable class="parameter">duration</replaceable></option></term>
<term><option>--duration=<replaceable class="parameter">duration</replaceable></option></term>
<listitem>
<para>
Specifies the test duration, in seconds. Longer durations
give slightly better accuracy, and are more likely to discover
problems with the system clock moving backwards. The default
test duration is 3 seconds.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c <replaceable class="parameter">cutoff</replaceable></option></term>
<term><option>--cutoff=<replaceable class="parameter">cutoff</replaceable></option></term>
<listitem>
<para>
Specifies the cutoff percentage for the list of exact observed
timing durations (that is, the changes in the system clock value
from one reading to the next). The list will end once the running
percentage total reaches or exceeds this value, except that the
largest observed duration will always be printed. The default
cutoff is 99.99.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-V</option></term>
<term><option>--version</option></term>
<listitem>
<para>
Print the <application>pg_test_timing</application> version and exit.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-?</option></term>
<term><option>--help</option></term>
<listitem>
<para>
Show help about <application>pg_test_timing</application> command line
arguments, and exit.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1>
<title>Usage</title>
<refsect2>
<title>Interpreting Results</title>
<para>
The first block of output has four columns, with rows showing a
shifted-by-one log2(ns) histogram of timing durations (that is, the
differences between successive clock readings). This is not the
classic log2(n+1) histogram as it counts zeros separately and then
switches to log2(ns) starting from value 1.
</para>
<para>
The columns are:
<itemizedlist spacing="compact">
<listitem>
<simpara>nanosecond value that is >= the durations in this
bucket</simpara>
</listitem>
<listitem>
<simpara>percentage of durations in this bucket</simpara>
</listitem>
<listitem>
<simpara>running-sum percentage of durations in this and previous
buckets</simpara>
</listitem>
<listitem>
<simpara>count of durations in this bucket</simpara>
</listitem>
</itemizedlist>
</para>
<para>
The second block of output goes into more detail, showing the exact
timing differences observed. For brevity this list is cut off when the
running-sum percentage exceeds the user-selectable cutoff value.
However, the largest observed difference is always shown.
</para>
<para>
The example results below show that 99.99% of timing loops took between
8 and 31 nanoseconds, with the worst case somewhere between 32768 and
65535 nanoseconds. In the second block, we can see that typical loop
time is 16 nanoseconds, and the readings appear to have full nanosecond
precision.
</para>
<para>
<screen><![CDATA[
Testing timing overhead for 3 seconds.
Average loop time including overhead: 16.40 ns
Histogram of timing durations:
<= ns % of total running % count
0 0.0000 0.0000 0
1 0.0000 0.0000 0
3 0.0000 0.0000 0
7 0.0000 0.0000 0
15 4.5452 4.5452 8313178
31 95.4527 99.9979 174581501
63 0.0001 99.9981 253
127 0.0001 99.9982 165
255 0.0000 99.9982 35
511 0.0000 99.9982 1
1023 0.0013 99.9994 2300
2047 0.0004 99.9998 690
4095 0.0000 99.9998 9
8191 0.0000 99.9998 8
16383 0.0002 100.0000 337
32767 0.0000 100.0000 2
65535 0.0000 100.0000 1
Observed timing durations up to 99.9900%:
ns % of total running % count
15 4.5452 4.5452 8313178
16 58.3785 62.9237 106773354
17 33.6840 96.6078 61607584
18 3.1151 99.7229 5697480
19 0.2638 99.9867 482570
20 0.0093 99.9960 17054
...
38051 0.0000 100.0000 1
]]></screen>
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-explain"/></member>
<member><ulink url="https://wiki.postgresql.org/wiki/Pg_test_timing">Wiki
discussion about timing</ulink></member>
</simplelist>
</refsect1>
</refentry>
|
