<!--
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.
  Systems that are slow to collect timing data can give less accurate
  <command>EXPLAIN ANALYZE</command> 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>-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>
   Good results will show most (>90%) individual timing calls take less than
   one microsecond. Average per loop overhead will be even lower, below 100
   nanoseconds. This example from an Intel i7-860 system using a TSC clock
   source shows excellent performance:

<screen><![CDATA[
Testing timing overhead for 3 seconds.
Per loop time including overhead: 35.96 ns
Histogram of timing durations:
  < us   % of total      count
     1     96.40465   80435604
     2      3.59518    2999652
     4      0.00015        126
     8      0.00002         13
    16      0.00000          2
]]></screen>
  </para>

  <para>
   Note that different units are used for the per loop time than the
   histogram. The loop can have resolution within a few nanoseconds (ns),
   while the individual timing calls can only resolve down to one microsecond
   (us).
  </para>

 </refsect2>
 <refsect2>
  <title>Measuring Executor Timing Overhead</title>

  <para>
   When the query executor is running a statement using
   <command>EXPLAIN ANALYZE</command>, individual operations are timed as well
   as showing a summary.  The overhead of your system can be checked by
   counting rows with the <application>psql</application> program:

<screen>
CREATE TABLE t AS SELECT * FROM generate_series(1,100000);
\timing
SELECT COUNT(*) FROM t;
EXPLAIN ANALYZE SELECT COUNT(*) FROM t;
</screen>
  </para>

  <para>
   The i7-860 system measured runs the count query in 9.8 ms while
   the <command>EXPLAIN ANALYZE</command> version takes 16.6 ms, each
   processing just over 100,000 rows.  That 6.8 ms difference means the timing