granicus.if.org Git - postgresql/blob - doc/src/sgml/monitoring.sgml

   1 <!-- doc/src/sgml/monitoring.sgml -->
   2
   3 <chapter id="monitoring">
   4  <title>Monitoring Database Activity</title>
   5
   6  <indexterm zone="monitoring">
   7   <primary>monitoring</primary>
   8   <secondary>database activity</secondary>
   9  </indexterm>
  10
  11  <indexterm zone="monitoring">
  12   <primary>database activity</primary>
  13   <secondary>monitoring</secondary>
  14  </indexterm>
  15
  16  <para>
  17   A database administrator frequently wonders, <quote>What is the system
  18   doing right now?</quote>
  19   This chapter discusses how to find that out.
  20  </para>
  21
  22   <para>
  23    Several tools are available for monitoring database activity and
  24    analyzing performance.  Most of this chapter is devoted to describing
  25    <productname>PostgreSQL</productname>'s statistics collector,
  26    but one should not neglect regular Unix monitoring programs such as
  27    <command>ps</>, <command>top</>, <command>iostat</>, and <command>vmstat</>.
  28    Also, once one has identified a
  29    poorly-performing query, further investigation might be needed using
  30    <productname>PostgreSQL</productname>'s <xref linkend="sql-explain"> command.
  31    <xref linkend="using-explain"> discusses <command>EXPLAIN</>
  32    and other methods for understanding the behavior of an individual
  33    query.
  34   </para>
  35
  36  <sect1 id="monitoring-ps">
  37   <title>Standard Unix Tools</title>
  38
  39   <indexterm zone="monitoring-ps">
  40    <primary>ps</primary>
  41    <secondary>to monitor activity</secondary>
  42   </indexterm>
  43
  44   <para>
  45    On most Unix platforms, <productname>PostgreSQL</productname> modifies its
  46    command title as reported by <command>ps</>, so that individual server
  47    processes can readily be identified.  A sample display is
  48
  49 <screen>
  50 $ ps auxww | grep ^postgres
  51 postgres  15551  0.0  0.1  57536  7132 pts/0    S    18:02   0:00 postgres -i
  52 postgres  15554  0.0  0.0  57536  1184 ?        Ss   18:02   0:00 postgres: writer process
  53 postgres  15555  0.0  0.0  57536   916 ?        Ss   18:02   0:00 postgres: checkpointer process
  54 postgres  15556  0.0  0.0  57536   916 ?        Ss   18:02   0:00 postgres: wal writer process
  55 postgres  15557  0.0  0.0  58504  2244 ?        Ss   18:02   0:00 postgres: autovacuum launcher process
  56 postgres  15558  0.0  0.0  17512  1068 ?        Ss   18:02   0:00 postgres: stats collector process
  57 postgres  15582  0.0  0.0  58772  3080 ?        Ss   18:04   0:00 postgres: joe runbug 127.0.0.1 idle
  58 postgres  15606  0.0  0.0  58772  3052 ?        Ss   18:07   0:00 postgres: tgl regression [local] SELECT waiting
  59 postgres  15610  0.0  0.0  58772  3056 ?        Ss   18:07   0:00 postgres: tgl regression [local] idle in transaction
  60 </screen>
  61
  62    (The appropriate invocation of <command>ps</> varies across different
  63    platforms, as do the details of what is shown.  This example is from a
  64    recent Linux system.)  The first process listed here is the
  65    master server process.  The command arguments
  66    shown for it are the same ones used when it was launched.  The next five
  67    processes are background worker processes automatically launched by the
  68    master process.  (The <quote>stats collector</> process will not be present
  69    if you have set the system not to start the statistics collector; likewise
  70    the <quote>autovacuum launcher</> process can be disabled.)
  71    Each of the remaining
  72    processes is a server process handling one client connection.  Each such
  73    process sets its command line display in the form
  74
  75 <screen>
  76 postgres: <replaceable>user</> <replaceable>database</> <replaceable>host</> <replaceable>activity</>
  77 </screen>
  78
  79   The user, database, and (client) host items remain the same for
  80   the life of the client connection, but the activity indicator changes.
  81   The activity can be <literal>idle</> (i.e., waiting for a client command),
  82   <literal>idle in transaction</> (waiting for client inside a <command>BEGIN</> block),
  83   or a command type name such as <literal>SELECT</>.  Also,
  84   <literal>waiting</> is appended if the server process is presently waiting
  85   on a lock held by another session.  In the above example we can infer
  86   that process 15606 is waiting for process 15610 to complete its transaction
  87   and thereby release some lock.  (Process 15610 must be the blocker, because
  88   there is no other active session.  In more complicated cases it would be
  89   necessary to look into the
  90   <link linkend="view-pg-locks"><structname>pg_locks</structname></link>
  91   system view to determine who is blocking whom.)
  92   </para>
  93
  94   <para>
  95    If you have turned off <xref linkend="guc-update-process-title"> then the
  96    activity indicator is not updated; the process title is set only once
  97    when a new process is launched.  On some platforms this saves a measurable
  98    amount of per-command overhead;  on others it's insignificant.
  99   </para>
 100
 101   <tip>
 102   <para>
 103   <productname>Solaris</productname> requires special handling. You must
 104   use <command>/usr/ucb/ps</command>, rather than
 105   <command>/bin/ps</command>. You also must use two <option>w</option>
 106   flags, not just one. In addition, your original invocation of the
 107   <command>postgres</command> command must have a shorter
 108   <command>ps</command> status display than that provided by each
 109   server process.  If you fail to do all three things, the <command>ps</>
 110   output for each server process will be the original <command>postgres</>
 111   command line.
 112   </para>
 113   </tip>
 114  </sect1>
 115
 116  <sect1 id="monitoring-stats">
 117   <title>The Statistics Collector</title>
 118
 119   <indexterm zone="monitoring-stats">
 120    <primary>statistics</primary>
 121   </indexterm>
 122
 123   <para>
 124    <productname>PostgreSQL</productname>'s <firstterm>statistics collector</>
 125    is a subsystem that supports collection and reporting of information about
 126    server activity.  Presently, the collector can count accesses to tables
 127    and indexes in both disk-block and individual-row terms.  It also tracks
 128    the total number of rows in each table, and information about vacuum and
 129    analyze actions for each table.  It can also count calls to user-defined
 130    functions and the total time spent in each one.
 131   </para>
 132
 133   <para>
 134    <productname>PostgreSQL</productname> also supports reporting of the exact
 135    command currently being executed by other server processes.  This
 136    facility is independent of the collector process.
 137   </para>
 138
 139  <sect2 id="monitoring-stats-setup">
 140   <title>Statistics Collection Configuration</title>
 141
 142   <para>
 143    Since collection of statistics adds some overhead to query execution,
 144    the system can be configured to collect or not collect information.
 145    This is controlled by configuration parameters that are normally set in
 146    <filename>postgresql.conf</>.  (See <xref linkend="runtime-config"> for
 147    details about setting configuration parameters.)
 148   </para>
 149
 150   <para>
 151    The parameter <xref linkend="guc-track-activities"> enables monitoring
 152    of the current command being executed by any server process.
 153   </para>
 154
 155   <para>
 156    The parameter <xref linkend="guc-track-counts"> controls whether
 157    statistics are collected about table and index accesses.
 158   </para>
 159
 160   <para>
 161    The parameter <xref linkend="guc-track-functions"> enables tracking of
 162    usage of user-defined functions.
 163   </para>
 164
 165   <para>
 166    The parameter <xref linkend="guc-track-io-timing"> enables monitoring
 167    of block read and write times.
 168   </para>
 169
 170   <para>
 171    Normally these parameters are set in <filename>postgresql.conf</> so
 172    that they apply to all server processes, but it is possible to turn
 173    them on or off in individual sessions using the <xref
 174    linkend="sql-set"> command. (To prevent
 175    ordinary users from hiding their activity from the administrator,
 176    only superusers are allowed to change these parameters with
 177    <command>SET</>.)
 178   </para>
 179
 180   <para>
 181    The statistics collector transmits the collected information to other
 182    <productname>PostgreSQL</productname> processes through temporary files.
 183    These files are stored in the directory named by the
 184    <xref linkend="guc-stats-temp-directory"> parameter,
 185    <filename>pg_stat_tmp</filename> by default.
 186    For better performance, <varname>stats_temp_directory</> can be
 187    pointed at a RAM-based file system, decreasing physical I/O requirements.
 188    When the server shuts down cleanly, a permanent copy of the statistics
 189    data is stored in the <filename>global</filename> subdirectory, so that
 190    statistics can be retained across server restarts.  When recovery is
 191    performed at server start (e.g. after immediate shutdown, server crash,
 192    and point-in-time recovery), all statistics counters are reset.
 193   </para>
 194
 195  </sect2>
 196
 197  <sect2 id="monitoring-stats-views">
 198   <title>Viewing Collected Statistics</title>
 199
 200   <para>
 201    Several predefined views, listed in <xref
 202    linkend="monitoring-stats-views-table">, are available to show the results
 203    of statistics collection.  Alternatively, one can
 204    build custom views using the underlying statistics functions, as discussed
 205    in <xref linkend="monitoring-stats-functions">.
 206   </para>
 207
 208   <para>
 209    When using the statistics to monitor current activity, it is important
 210    to realize that the information does not update instantaneously.
 211    Each individual server process transmits new statistical counts to
 212    the collector just before going idle; so a query or transaction still in
 213    progress does not affect the displayed totals.  Also, the collector itself
 214    emits a new report at most once per <varname>PGSTAT_STAT_INTERVAL</varname>
 215    milliseconds (500 ms unless altered while building the server).  So the
 216    displayed information lags behind actual activity.  However, current-query
 217    information collected by <varname>track_activities</varname> is
 218    always up-to-date.
 219   </para>
 220
 221   <para>
 222    Another important point is that when a server process is asked to display
 223    any of these statistics, it first fetches the most recent report emitted by
 224    the collector process and then continues to use this snapshot for all
 225    statistical views and functions until the end of its current transaction.
 226    So the statistics will show static information as long as you continue the
 227    current transaction.  Similarly, information about the current queries of
 228    all sessions is collected when any such information is first requested
 229    within a transaction, and the same information will be displayed throughout
 230    the transaction.
 231    This is a feature, not a bug, because it allows you to perform several
 232    queries on the statistics and correlate the results without worrying that
 233    the numbers are changing underneath you.  But if you want to see new
 234    results with each query, be sure to do the queries outside any transaction
 235    block.  Alternatively, you can invoke
 236    <function>pg_stat_clear_snapshot</function>(), which will discard the
 237    current transaction's statistics snapshot (if any).  The next use of
 238    statistical information will cause a new snapshot to be fetched.
 239   </para>
 240
 241   <para>
 242    A transaction can also see its own statistics (as yet untransmitted to the
 243    collector) in the views <structname>pg_stat_xact_all_tables</>,
 244    <structname>pg_stat_xact_sys_tables</>,
 245    <structname>pg_stat_xact_user_tables</>, and
 246    <structname>pg_stat_xact_user_functions</>.  These numbers do not act as
 247    stated above; instead they update continuously throughout the transaction.
 248   </para>
 249
 250   <table id="monitoring-stats-views-table">
 251    <title>Standard Statistics Views</title>
 252
 253    <tgroup cols="2">
 254     <thead>
 255      <row>
 256       <entry>View Name</entry>
 257       <entry>Description</entry>
 258      </row>
 259     </thead>
 260
 261     <tbody>
 262      <row>
 263       <entry>
 264        <structname>pg_stat_activity</structname>
 265        <indexterm><primary>pg_stat_activity</primary></indexterm>
 266       </entry>
 267       <entry>
 268        One row per server process, showing information related to
 269        the current activity of that process, such as state and current query.
 270        See <xref linkend="pg-stat-activity-view"> for details.
 271       </entry>
 272      </row>
 273
 274      <row>
 275       <entry><structname>pg_stat_archiver</><indexterm><primary>pg_stat_archiver</primary></indexterm></entry>
 276       <entry>One row only, showing statistics about the
 277        WAL archiver process's activity. See
 278        <xref linkend="pg-stat-archiver-view"> for details.
 279       </entry>
 280      </row>
 281
 282      <row>
 283       <entry><structname>pg_stat_bgwriter</><indexterm><primary>pg_stat_bgwriter</primary></indexterm></entry>
 284       <entry>One row only, showing statistics about the
 285        background writer process's activity. See
 286        <xref linkend="pg-stat-bgwriter-view"> for details.
 287      </entry>
 288      </row>
 289
 290      <row>
 291       <entry><structname>pg_stat_database</><indexterm><primary>pg_stat_database</primary></indexterm></entry>
 292       <entry>One row per database, showing database-wide statistics. See
 293        <xref linkend="pg-stat-database-view"> for details.
 294       </entry>
 295      </row>
 296
 297      <row>
 298       <entry><structname>pg_stat_all_tables</><indexterm><primary>pg_stat_all_tables</primary></indexterm></entry>
 299       <entry>
 300        One row for each table in the current database, showing statistics
 301        about accesses to that specific table.
 302        See <xref linkend="pg-stat-all-tables-view"> for details.
 303       </entry>
 304      </row>
 305
 306      <row>
 307       <entry><structname>pg_stat_sys_tables</><indexterm><primary>pg_stat_sys_tables</primary></indexterm></entry>
 308       <entry>Same as <structname>pg_stat_all_tables</>, except that only
 309       system tables are shown.</entry>
 310      </row>
 311
 312      <row>
 313       <entry><structname>pg_stat_user_tables</><indexterm><primary>pg_stat_user_tables</primary></indexterm></entry>
 314       <entry>Same as <structname>pg_stat_all_tables</>, except that only user
 315       tables are shown.</entry>
 316      </row>
 317
 318      <row>
 319       <entry><structname>pg_stat_xact_all_tables</><indexterm><primary>pg_stat_xact_all_tables</primary></indexterm></entry>
 320       <entry>Similar to <structname>pg_stat_all_tables</>, but counts actions
 321       taken so far within the current transaction (which are <emphasis>not</>
 322       yet included in <structname>pg_stat_all_tables</> and related views).
 323       The columns for numbers of live and dead rows and vacuum and
 324       analyze actions are not present in this view.</entry>
 325      </row>
 326
 327      <row>
 328       <entry><structname>pg_stat_xact_sys_tables</><indexterm><primary>pg_stat_xact_sys_tables</primary></indexterm></entry>
 329       <entry>Same as <structname>pg_stat_xact_all_tables</>, except that only
 330       system tables are shown.</entry>
 331      </row>
 332
 333      <row>
 334       <entry><structname>pg_stat_xact_user_tables</><indexterm><primary>pg_stat_xact_user_tables</primary></indexterm></entry>
 335       <entry>Same as <structname>pg_stat_xact_all_tables</>, except that only
 336       user tables are shown.</entry>
 337      </row>
 338
 339      <row>
 340       <entry><structname>pg_stat_all_indexes</><indexterm><primary>pg_stat_all_indexes</primary></indexterm></entry>
 341       <entry>
 342        One row for each index in the current database, showing statistics
 343        about accesses to that specific index.
 344        See <xref linkend="pg-stat-all-indexes-view"> for details.
 345       </entry>
 346      </row>
 347
 348      <row>
 349       <entry><structname>pg_stat_sys_indexes</><indexterm><primary>pg_stat_sys_indexes</primary></indexterm></entry>
 350       <entry>Same as <structname>pg_stat_all_indexes</>, except that only
 351       indexes on system tables are shown.</entry>
 352      </row>
 353
 354      <row>
 355       <entry><structname>pg_stat_user_indexes</><indexterm><primary>pg_stat_user_indexes</primary></indexterm></entry>
 356       <entry>Same as <structname>pg_stat_all_indexes</>, except that only
 357       indexes on user tables are shown.</entry>
 358      </row>
 359
 360      <row>
 361       <entry><structname>pg_statio_all_tables</><indexterm><primary>pg_statio_all_tables</primary></indexterm></entry>
 362       <entry>
 363        One row for each table in the current database, showing statistics
 364        about I/O on that specific table.
 365        See <xref linkend="pg-statio-all-tables-view"> for details.
 366       </entry>
 367      </row>
 368
 369      <row>
 370       <entry><structname>pg_statio_sys_tables</><indexterm><primary>pg_statio_sys_tables</primary></indexterm></entry>
 371       <entry>Same as <structname>pg_statio_all_tables</>, except that only
 372       system tables are shown.</entry>
 373      </row>
 374
 375      <row>
 376       <entry><structname>pg_statio_user_tables</><indexterm><primary>pg_statio_user_tables</primary></indexterm></entry>
 377       <entry>Same as <structname>pg_statio_all_tables</>, except that only
 378       user tables are shown.</entry>
 379      </row>
 380
 381      <row>
 382       <entry><structname>pg_statio_all_indexes</><indexterm><primary>pg_statio_all_indexes</primary></indexterm></entry>
 383       <entry>
 384        One row for each index in the current database,
 385        showing statistics about I/O on that specific index.
 386        See <xref linkend="pg-statio-all-indexes-view"> for details.
 387       </entry>
 388      </row>
 389
 390      <row>
 391       <entry><structname>pg_statio_sys_indexes</><indexterm><primary>pg_statio_sys_indexes</primary></indexterm></entry>
 392       <entry>Same as <structname>pg_statio_all_indexes</>, except that only
 393       indexes on system tables are shown.</entry>
 394      </row>
 395
 396      <row>
 397       <entry><structname>pg_statio_user_indexes</><indexterm><primary>pg_statio_user_indexes</primary></indexterm></entry>
 398       <entry>Same as <structname>pg_statio_all_indexes</>, except that only
 399       indexes on user tables are shown.</entry>
 400      </row>
 401
 402      <row>
 403       <entry><structname>pg_statio_all_sequences</><indexterm><primary>pg_statio_all_sequences</primary></indexterm></entry>
 404      <entry>
 405        One row for each sequence in the current database,
 406        showing statistics about I/O on that specific sequence.
 407        See <xref linkend="pg-statio-all-sequences-view"> for details.
 408      </entry>
 409      </row>
 410
 411      <row>
 412       <entry><structname>pg_statio_sys_sequences</><indexterm><primary>pg_statio_sys_sequences</primary></indexterm></entry>
 413       <entry>Same as <structname>pg_statio_all_sequences</>, except that only
 414       system sequences are shown.  (Presently, no system sequences are defined,
 415       so this view is always empty.)</entry>
 416      </row>
 417
 418      <row>
 419       <entry><structname>pg_statio_user_sequences</><indexterm><primary>pg_statio_user_sequences</primary></indexterm></entry>
 420       <entry>Same as <structname>pg_statio_all_sequences</>, except that only
 421       user sequences are shown.</entry>
 422      </row>
 423
 424      <row>
 425       <entry><structname>pg_stat_user_functions</><indexterm><primary>pg_stat_user_functions</primary></indexterm></entry>
 426       <entry>
 427        One row for each tracked function, showing statistics
 428        about executions of that function. See
 429        <xref linkend="pg-stat-user-functions-view"> for details.
 430       </entry>
 431      </row>
 432
 433      <row>
 434       <entry><structname>pg_stat_xact_user_functions</><indexterm><primary>pg_stat_xact_user_functions</primary></indexterm></entry>
 435       <entry>Similar to <structname>pg_stat_user_functions</>, but counts only
 436       calls during the current transaction (which are <emphasis>not</>
 437       yet included in <structname>pg_stat_user_functions</>).</entry>
 438      </row>
 439
 440      <row>
 441       <entry><structname>pg_stat_replication</><indexterm><primary>pg_stat_replication</primary></indexterm></entry>
 442       <entry>One row per WAL sender process, showing statistics about
 443        replication to that sender's connected standby server.
 444        See <xref linkend="pg-stat-replication-view"> for details.
 445       </entry>
 446      </row>
 447
 448      <row>
 449       <entry><structname>pg_stat_database_conflicts</><indexterm><primary>pg_stat_database_conflicts</primary></indexterm></entry>
 450       <entry>
 451        One row per database, showing database-wide statistics about
 452        query cancels due to conflict with recovery on standby servers.
 453        See <xref linkend="pg-stat-database-conflicts-view"> for details.
 454       </entry>
 455      </row>
 456
 457     </tbody>
 458    </tgroup>
 459   </table>
 460
 461   <para>
 462    The per-index statistics are particularly useful to determine which
 463    indexes are being used and how effective they are.
 464   </para>
 465
 466   <para>
 467    The <structname>pg_statio_</> views are primarily useful to
 468    determine the effectiveness of the buffer cache.  When the number
 469    of actual disk reads is much smaller than the number of buffer
 470    hits, then the cache is satisfying most read requests without
 471    invoking a kernel call. However, these statistics do not give the
 472    entire story: due to the way in which <productname>PostgreSQL</>
 473    handles disk I/O, data that is not in the
 474    <productname>PostgreSQL</> buffer cache might still reside in the
 475    kernel's I/O cache, and might therefore still be fetched without
 476    requiring a physical read. Users interested in obtaining more
 477    detailed information on <productname>PostgreSQL</> I/O behavior are
 478    advised to use the <productname>PostgreSQL</> statistics collector
 479    in combination with operating system utilities that allow insight
 480    into the kernel's handling of I/O.
 481   </para>
 482
 483
 484   <table id="pg-stat-activity-view" xreflabel="pg_stat_activity">
 485    <title><structname>pg_stat_activity</structname> View</title>
 486
 487    <tgroup cols="3">
 488     <thead>
 489     <row>
 490       <entry>Column</entry>
 491       <entry>Type</entry>
 492       <entry>Description</entry>
 493      </row>
 494     </thead>
 495
 496    <tbody>
 497     <row>
 498      <entry><structfield>datid</></entry>
 499      <entry><type>oid</></entry>
 500      <entry>OID of the database this backend is connected to</entry>
 501     </row>
 502     <row>
 503      <entry><structfield>datname</></entry>
 504      <entry><type>name</></entry>
 505      <entry>Name of the database this backend is connected to</entry>
 506     </row>
 507     <row>
 508      <entry><structfield>pid</></entry>
 509      <entry><type>integer</></entry>
 510      <entry>Process ID of this backend</entry>
 511     </row>
 512     <row>
 513      <entry><structfield>usesysid</></entry>
 514      <entry><type>oid</></entry>
 515      <entry>OID of the user logged into this backend</entry>
 516     </row>
 517     <row>
 518      <entry><structfield>usename</></entry>
 519      <entry><type>name</></entry>
 520      <entry>Name of the user logged into this backend</entry>
 521     </row>
 522     <row>
 523      <entry><structfield>application_name</></entry>
 524      <entry><type>text</></entry>
 525      <entry>Name of the application that is connected
 526       to this backend</entry>
 527     </row>
 528     <row>
 529      <entry><structfield>client_addr</></entry>
 530      <entry><type>inet</></entry>
 531      <entry>IP address of the client connected to this backend.
 532       If this field is null, it indicates either that the client is
 533       connected via a Unix socket on the server machine or that this is an
 534       internal process such as autovacuum.
 535      </entry>
 536     </row>
 537     <row>
 538      <entry><structfield>client_hostname</></entry>
 539      <entry><type>text</></entry>
 540      <entry>Host name of the connected client, as reported by a
 541       reverse DNS lookup of <structfield>client_addr</>. This field will
 542       only be non-null for IP connections, and only when <xref
 543       linkend="guc-log-hostname"> is enabled.
 544      </entry>
 545     </row>
 546     <row>
 547      <entry><structfield>client_port</></entry>
 548      <entry><type>integer</></entry>
 549      <entry>TCP port number that the client is using for communication
 550       with this backend, or <literal>-1</> if a Unix socket is used
 551      </entry>
 552     </row>
 553     <row>
 554      <entry><structfield>backend_start</></entry>
 555      <entry><type>timestamp with time zone</></entry>
 556      <entry>Time when this process was started, i.e., when the
 557       client connected to the server
 558      </entry>
 559     </row>
 560     <row>
 561      <entry><structfield>xact_start</></entry>
 562      <entry><type>timestamp with time zone</></entry>
 563      <entry>Time when this process' current transaction was started, or null
 564       if no transaction is active. If the current
 565       query is the first of its transaction, this column is equal to the
 566       <structfield>query_start</> column.
 567      </entry>
 568     </row>
 569     <row>
 570      <entry><structfield>query_start</></entry>
 571      <entry><type>timestamp with time zone</></entry>
 572      <entry>Time when the currently active query was started, or if
 573       <structfield>state</> is not <literal>active</>, when the last query
 574       was started
 575      </entry>
 576     </row>
 577     <row>
 578      <entry><structfield>state_change</></entry>
 579      <entry><type>timestamp with time zone</></entry>
 580      <entry>Time when the <structfield>state</> was last changed</entry>
 581     </row>
 582     <row>
 583      <entry><structfield>waiting</></entry>
 584      <entry><type>boolean</></entry>
 585      <entry>True if this backend is currently waiting on a lock</entry>
 586     </row>
 587     <row>
 588      <entry><structfield>state</></entry>
 589      <entry><type>text</></entry>
 590      <entry>Current overall state of this backend.
 591        Possible values are:
 592        <itemizedlist>
 593          <listitem>
 594           <para>
 595            <literal>active</>: The backend is executing a query.
 596           </para>
 597          </listitem>
 598          <listitem>
 599           <para>
 600            <literal>idle</>: The backend is waiting for a new client command.
 601           </para>
 602          </listitem>
 603          <listitem>
 604           <para>
 605            <literal>idle in transaction</>: The backend is in a transaction,
 606            but is not currently executing a query.
 607           </para>
 608          </listitem>
 609          <listitem>
 610           <para>
 611            <literal>idle in transaction (aborted)</>: This state is similar to
 612            <literal>idle in transaction</>, except one of the statements in
 613            the transaction caused an error.
 614           </para>
 615          </listitem>
 616          <listitem>
 617           <para>
 618            <literal>fastpath function call</>: The backend is executing a
 619            fast-path function.
 620           </para>
 621          </listitem>
 622          <listitem>
 623            <para>
 624            <literal>disabled</>: This state is reported if <xref
 625            linkend="guc-track-activities"> is disabled in this backend.
 626           </para>
 627          </listitem>
 628        </itemizedlist>
 629      </entry>
 630     </row>
 631     <row>
 632      <entry><structfield>backend_xid</structfield></entry>
 633      <entry><type>xid</type></entry>
 634      <entry>Toplevel transaction identifier of this backend, if any.</entry>
 635     </row>
 636     <row>
 637      <entry><structfield>backend_xmin</structfield></entry>
 638      <entry><type>xid</type></entry>
 639      <entry>The current backend's <literal>xmin</> horizon.</entry>
 640     </row>
 641     <row>
 642      <entry><structfield>query</></entry>
 643      <entry><type>text</></entry>
 644      <entry>Text of this backend's most recent query. If
 645       <structfield>state</> is <literal>active</> this field shows the
 646       currently executing query. In all other states, it shows the last query
 647       that was executed.
 648      </entry>
 649     </row>
 650    </tbody>
 651    </tgroup>
 652   </table>
 653
 654   <para>
 655    The <structname>pg_stat_activity</structname> view will have one row
 656    per server process, showing information related to
 657    the current activity of that process.
 658   </para>
 659
 660   <note>
 661    <para>
 662     The <structfield>waiting</> and <structfield>state</> columns are
 663     independent.  If a backend is in the <literal>active</> state,
 664     it may or may not be <literal>waiting</>.  If the state is
 665     <literal>active</> and <structfield>waiting</> is true, it means
 666     that a query is being executed, but is being blocked by a lock
 667     somewhere in the system.
 668    </para>
 669   </note>
 670
 671   <table id="pg-stat-archiver-view" xreflabel="pg_stat_archiver">
 672    <title><structname>pg_stat_archiver</structname> View</title>
 673
 674    <tgroup cols="3">
 675     <thead>
 676      <row>
 677       <entry>Column</entry>
 678       <entry>Type</entry>
 679       <entry>Description</entry>
 680      </row>
 681     </thead>
 682
 683     <tbody>
 684      <row>
 685       <entry><structfield>archived_count</></entry>
 686       <entry><type>bigint</type></entry>
 687       <entry>Number of WAL files that have been successfully archived</entry>
 688      </row>
 689      <row>
 690       <entry><structfield>last_archived_wal</></entry>
 691       <entry><type>text</type></entry>
 692       <entry>Name of the last WAL file successfully archived</entry>
 693      </row>
 694      <row>
 695       <entry><structfield>last_archived_time</></entry>
 696       <entry><type>timestamp with time zone</type></entry>
 697       <entry>Time of the last successful archive operation</entry>
 698      </row>
 699      <row>
 700       <entry><structfield>failed_count</></entry>
 701       <entry><type>bigint</type></entry>
 702       <entry>Number of failed attempts for archiving WAL files</entry>
 703      </row>
 704      <row>
 705       <entry><structfield>last_failed_wal</></entry>
 706       <entry><type>text</type></entry>
 707       <entry>Name of the WAL file of the last failed archival operation</entry>
 708      </row>
 709      <row>
 710       <entry><structfield>last_failed_time</></entry>
 711       <entry><type>timestamp with time zone</type></entry>
 712       <entry>Time of the last failed archival operation</entry>
 713      </row>
 714      <row>
 715       <entry><structfield>stats_reset</></entry>
 716       <entry><type>timestamp with time zone</type></entry>
 717       <entry>Time at which these statistics were last reset</entry>
 718      </row>
 719     </tbody>
 720    </tgroup>
 721   </table>
 722
 723   <para>
 724    The <structname>pg_stat_archiver</structname> view will always have a
 725    single row, containing data about the archiver process of the cluster.
 726   </para>
 727
 728   <table id="pg-stat-bgwriter-view" xreflabel="pg_stat_bgwriter">
 729    <title><structname>pg_stat_bgwriter</structname> View</title>
 730
 731    <tgroup cols="3">
 732     <thead>
 733     <row>
 734       <entry>Column</entry>
 735       <entry>Type</entry>
 736       <entry>Description</entry>
 737      </row>
 738     </thead>
 739
 740     <tbody>
 741      <row>
 742       <entry><structfield>checkpoints_timed</></entry>
 743       <entry><type>bigint</type></entry>
 744       <entry>Number of scheduled checkpoints that have been performed</entry>
 745      </row>
 746      <row>
 747       <entry><structfield>checkpoints_req</></entry>
 748       <entry><type>bigint</type></entry>
 749       <entry>Number of requested checkpoints that have been performed</entry>
 750      </row>
 751      <row>
 752       <entry><structfield>checkpoint_write_time</></entry>
 753       <entry><type>double precision</type></entry>
 754       <entry>
 755         Total amount of time that has been spent in the portion of
 756         checkpoint processing where files are written to disk, in milliseconds
 757       </entry>
 758      </row>
 759      <row>
 760       <entry><structfield>checkpoint_sync_time</></entry>
 761       <entry><type>double precision</type></entry>
 762       <entry>
 763         Total amount of time that has been spent in the portion of
 764         checkpoint processing where files are synchronized to disk, in
 765         milliseconds
 766       </entry>
 767      </row>
 768      <row>
 769       <entry><structfield>buffers_checkpoint</></entry>
 770       <entry><type>bigint</type></entry>
 771       <entry>Number of buffers written during checkpoints</entry>
 772      </row>
 773      <row>
 774       <entry><structfield>buffers_clean</></entry>
 775       <entry><type>bigint</type></entry>
 776       <entry>Number of buffers written by the background writer</entry>
 777      </row>
 778      <row>
 779       <entry><structfield>maxwritten_clean</></entry>
 780       <entry><type>bigint</type></entry>
 781       <entry>Number of times the background writer stopped a cleaning
 782        scan because it had written too many buffers</entry>
 783      </row>
 784      <row>
 785       <entry><structfield>buffers_backend</></entry>
 786       <entry><type>bigint</type></entry>
 787       <entry>Number of buffers written directly by a backend</entry>
 788      </row>
 789      <row>
 790       <entry><structfield>buffers_backend_fsync</></entry>
 791       <entry><type>bigint</type></entry>
 792       <entry>Number of times a backend had to execute its own
 793        <function>fsync</> call (normally the background writer handles those
 794        even when the backend does its own write)</entry>
 795      </row>
 796      <row>
 797       <entry><structfield>buffers_alloc</></entry>
 798       <entry><type>bigint</type></entry>
 799       <entry>Number of buffers allocated</entry>
 800      </row>
 801      <row>
 802       <entry><structfield>stats_reset</></entry>
 803       <entry><type>timestamp with time zone</type></entry>
 804       <entry>Time at which these statistics were last reset</entry>
 805      </row>
 806     </tbody>
 807     </tgroup>
 808   </table>
 809
 810   <para>
 811    The <structname>pg_stat_bgwriter</structname> view will always have a
 812    single row, containing global data for the cluster.
 813   </para>
 814
 815   <table id="pg-stat-database-view" xreflabel="pg_stat_database">
 816    <title><structname>pg_stat_database</structname> View</title>
 817    <tgroup cols="3">
 818     <thead>
 819     <row>
 820       <entry>Column</entry>
 821       <entry>Type</entry>
 822       <entry>Description</entry>
 823      </row>
 824     </thead>
 825
 826    <tbody>
 827     <row>
 828      <entry><structfield>datid</></entry>
 829      <entry><type>oid</></entry>
 830      <entry>OID of a database</entry>
 831     </row>
 832     <row>
 833      <entry><structfield>datname</></entry>
 834      <entry><type>name</></entry>
 835      <entry>Name of this database</entry>
 836     </row>
 837     <row>
 838      <entry><structfield>numbackends</></entry>
 839      <entry><type>integer</></entry>
 840      <entry>Number of backends currently connected to this database.
 841      This is the only column in this view that returns a value reflecting
 842      current state; all other columns return the accumulated values since
 843      the last reset.</entry>
 844     </row>
 845     <row>
 846      <entry><structfield>xact_commit</></entry>
 847      <entry><type>bigint</></entry>
 848      <entry>Number of transactions in this database that have been
 849       committed</entry>
 850     </row>
 851     <row>
 852      <entry><structfield>xact_rollback</></entry>
 853      <entry><type>bigint</></entry>
 854      <entry>Number of transactions in this database that have been
 855       rolled back</entry>
 856     </row>
 857     <row>
 858      <entry><structfield>blks_read</></entry>
 859      <entry><type>bigint</></entry>
 860      <entry>Number of disk blocks read in this database</entry>
 861     </row>
 862     <row>
 863      <entry><structfield>blks_hit</></entry>
 864      <entry><type>bigint</></entry>
 865      <entry>Number of times disk blocks were found already in the buffer
 866       cache, so that a read was not necessary (this only includes hits in the
 867       PostgreSQL buffer cache, not the operating system's file system cache)
 868      </entry>
 869     </row>
 870     <row>
 871      <entry><structfield>tup_returned</></entry>
 872      <entry><type>bigint</></entry>
 873      <entry>Number of rows returned by queries in this database</entry>
 874     </row>
 875     <row>
 876      <entry><structfield>tup_fetched</></entry>
 877      <entry><type>bigint</></entry>
 878      <entry>Number of rows fetched by queries in this database</entry>
 879     </row>
 880     <row>
 881      <entry><structfield>tup_inserted</></entry>
 882      <entry><type>bigint</></entry>
 883      <entry>Number of rows inserted by queries in this database</entry>
 884     </row>
 885     <row>
 886      <entry><structfield>tup_updated</></entry>
 887      <entry><type>bigint</></entry>
 888      <entry>Number of rows updated by queries in this database</entry>
 889     </row>
 890     <row>
 891      <entry><structfield>tup_deleted</></entry>
 892      <entry><type>bigint</></entry>
 893      <entry>Number of rows deleted by queries in this database</entry>
 894     </row>
 895     <row>
 896      <entry><structfield>conflicts</></entry>
 897      <entry><type>bigint</></entry>
 898      <entry>Number of queries canceled due to conflicts with recovery
 899       in this database. (Conflicts occur only on standby servers; see
 900       <xref linkend="pg-stat-database-conflicts-view"> for details.)
 901      </entry>
 902     </row>
 903     <row>
 904      <entry><structfield>temp_files</></entry>
 905      <entry><type>bigint</></entry>
 906      <entry>Number of temporary files created by queries in this database.
 907       All temporary files are counted, regardless of why the temporary file
 908       was created (e.g., sorting or hashing), and regardless of the
 909       <xref linkend="guc-log-temp-files"> setting.
 910      </entry>
 911     </row>
 912     <row>
 913      <entry><structfield>temp_bytes</></entry>
 914      <entry><type>bigint</></entry>
 915      <entry>Total amount of data written to temporary files by queries in
 916       this database. All temporary files are counted, regardless of why
 917       the temporary file was created, and
 918       regardless of the <xref linkend="guc-log-temp-files"> setting.
 919      </entry>
 920     </row>
 921     <row>
 922      <entry><structfield>deadlocks</></entry>
 923      <entry><type>bigint</></entry>
 924      <entry>Number of deadlocks detected in this database</entry>
 925     </row>
 926     <row>
 927      <entry><structfield>blk_read_time</></entry>
 928      <entry><type>double precision</></entry>
 929      <entry>Time spent reading data file blocks by backends in this database,
 930       in milliseconds</entry>
 931     </row>
 932     <row>
 933      <entry><structfield>blk_write_time</></entry>
 934      <entry><type>double precision</></entry>
 935      <entry>Time spent writing data file blocks by backends in this database,
 936       in milliseconds</entry>
 937     </row>
 938     <row>
 939      <entry><structfield>stats_reset</></entry>
 940      <entry><type>timestamp with time zone</></entry>
 941      <entry>Time at which these statistics were last reset</entry>
 942     </row>
 943    </tbody>
 944    </tgroup>
 945   </table>
 946
 947   <para>
 948    The <structname>pg_stat_database</structname> view will contain one row
 949    for each database in the cluster, showing database-wide statistics.
 950   </para>
 951
 952   <table id="pg-stat-all-tables-view" xreflabel="pg_stat_all_tables">
 953    <title><structname>pg_stat_all_tables</structname> View</title>
 954    <tgroup cols="3">
 955     <thead>
 956     <row>
 957       <entry>Column</entry>
 958       <entry>Type</entry>
 959       <entry>Description</entry>
 960      </row>
 961     </thead>
 962
 963    <tbody>
 964     <row>
 965      <entry><structfield>relid</></entry>
 966      <entry><type>oid</></entry>
 967      <entry>OID of a table</entry>
 968     </row>
 969     <row>
 970      <entry><structfield>schemaname</></entry>
 971      <entry><type>name</></entry>
 972      <entry>Name of the schema that this table is in</entry>
 973     </row>
 974     <row>
 975      <entry><structfield>relname</></entry>
 976      <entry><type>name</></entry>
 977      <entry>Name of this table</entry>
 978     </row>
 979     <row>
 980      <entry><structfield>seq_scan</></entry>
 981      <entry><type>bigint</></entry>
 982      <entry>Number of sequential scans initiated on this table</entry>
 983     </row>
 984     <row>
 985      <entry><structfield>seq_tup_read</></entry>
 986      <entry><type>bigint</></entry>
 987      <entry>Number of live rows fetched by sequential scans</entry>
 988     </row>
 989     <row>
 990      <entry><structfield>idx_scan</></entry>
 991      <entry><type>bigint</></entry>
 992      <entry>Number of index scans initiated on this table</entry>
 993     </row>
 994     <row>
 995      <entry><structfield>idx_tup_fetch</></entry>
 996      <entry><type>bigint</></entry>
 997      <entry>Number of live rows fetched by index scans</entry>
 998     </row>
 999     <row>
1000      <entry><structfield>n_tup_ins</></entry>
1001      <entry><type>bigint</></entry>
1002      <entry>Number of rows inserted</entry>
1003     </row>
1004     <row>
1005      <entry><structfield>n_tup_upd</></entry>
1006      <entry><type>bigint</></entry>
1007      <entry>Number of rows updated</entry>
1008     </row>
1009     <row>
1010      <entry><structfield>n_tup_del</></entry>
1011      <entry><type>bigint</></entry>
1012      <entry>Number of rows deleted</entry>
1013     </row>
1014     <row>
1015      <entry><structfield>n_tup_hot_upd</></entry>
1016      <entry><type>bigint</></entry>
1017      <entry>Number of rows HOT updated (i.e., with no separate index
1018       update required)</entry>
1019     </row>
1020     <row>
1021      <entry><structfield>n_live_tup</></entry>
1022      <entry><type>bigint</></entry>
1023      <entry>Estimated number of live rows</entry>
1024     </row>
1025     <row>
1026      <entry><structfield>n_dead_tup</></entry>
1027      <entry><type>bigint</></entry>
1028      <entry>Estimated number of dead rows</entry>
1029     </row>
1030     <row>
1031      <entry><structfield>n_mod_since_analyze</></entry>
1032      <entry><type>bigint</></entry>
1033      <entry>Estimated number of rows modified since this table was last analyzed</entry>
1034     </row>
1035     <row>
1036      <entry><structfield>last_vacuum</></entry>
1037      <entry><type>timestamp with time zone</></entry>
1038      <entry>Last time at which this table was manually vacuumed
1039       (not counting <command>VACUUM FULL</>)</entry>
1040     </row>
1041     <row>
1042      <entry><structfield>last_autovacuum</></entry>
1043      <entry><type>timestamp with time zone</></entry>
1044      <entry>Last time at which this table was vacuumed by the autovacuum
1045       daemon</entry>
1046     </row>
1047     <row>
1048      <entry><structfield>last_analyze</></entry>
1049      <entry><type>timestamp with time zone</></entry>
1050      <entry>Last time at which this table was manually analyzed</entry>
1051     </row>
1052     <row>
1053      <entry><structfield>last_autoanalyze</></entry>
1054      <entry><type>timestamp with time zone</></entry>
1055      <entry>Last time at which this table was analyzed by the autovacuum
1056       daemon</entry>
1057     </row>
1058     <row>
1059      <entry><structfield>vacuum_count</></entry>
1060      <entry><type>bigint</></entry>
1061      <entry>Number of times this table has been manually vacuumed
1062       (not counting <command>VACUUM FULL</>)</entry>
1063     </row>
1064     <row>
1065      <entry><structfield>autovacuum_count</></entry>
1066      <entry><type>bigint</></entry>
1067      <entry>Number of times this table has been vacuumed by the autovacuum
1068       daemon</entry>
1069     </row>
1070     <row>
1071      <entry><structfield>analyze_count</></entry>
1072      <entry><type>bigint</></entry>
1073      <entry>Number of times this table has been manually analyzed</entry>
1074     </row>
1075     <row>
1076      <entry><structfield>autoanalyze_count</></entry>
1077      <entry><type>bigint</></entry>
1078      <entry>Number of times this table has been analyzed by the autovacuum
1079       daemon</entry>
1080     </row>
1081    </tbody>
1082    </tgroup>
1083   </table>
1084
1085   <para>
1086    The <structname>pg_stat_all_tables</structname> view will contain
1087    one row for each table in the current database (including TOAST
1088    tables), showing statistics about accesses to that specific table. The
1089    <structname>pg_stat_user_tables</structname> and
1090    <structname>pg_stat_sys_tables</structname> views
1091    contain the same information,
1092    but filtered to only show user and system tables respectively.
1093   </para>
1094
1095   <table id="pg-stat-all-indexes-view" xreflabel="pg_stat_all_indexes">
1096    <title><structname>pg_stat_all_indexes</structname> View</title>
1097    <tgroup cols="3">
1098     <thead>
1099     <row>
1100       <entry>Column</entry>
1101       <entry>Type</entry>
1102       <entry>Description</entry>
1103      </row>
1104     </thead>
1105
1106    <tbody>
1107     <row>
1108      <entry><structfield>relid</></entry>
1109      <entry><type>oid</></entry>
1110      <entry>OID of the table for this index</entry>
1111     </row>
1112     <row>
1113      <entry><structfield>indexrelid</></entry>
1114      <entry><type>oid</></entry>
1115      <entry>OID of this index</entry>
1116     </row>
1117     <row>
1118      <entry><structfield>schemaname</></entry>
1119      <entry><type>name</></entry>
1120      <entry>Name of the schema this index is in</entry>
1121     </row>
1122     <row>
1123      <entry><structfield>relname</></entry>
1124      <entry><type>name</></entry>
1125      <entry>Name of the table for this index</entry>
1126     </row>
1127     <row>
1128      <entry><structfield>indexrelname</></entry>
1129      <entry><type>name</></entry>
1130      <entry>Name of this index</entry>
1131     </row>
1132     <row>
1133      <entry><structfield>idx_scan</></entry>
1134      <entry><type>bigint</></entry>
1135      <entry>Number of index scans initiated on this index</entry>
1136     </row>
1137     <row>
1138      <entry><structfield>idx_tup_read</></entry>
1139      <entry><type>bigint</></entry>
1140      <entry>Number of index entries returned by scans on this index</entry>
1141     </row>
1142     <row>
1143      <entry><structfield>idx_tup_fetch</></entry>
1144      <entry><type>bigint</></entry>
1145      <entry>Number of live table rows fetched by simple index scans using this
1146       index</entry>
1147     </row>
1148    </tbody>
1149    </tgroup>
1150   </table>
1151
1152   <para>
1153    The <structname>pg_stat_all_indexes</structname> view will contain
1154    one row for each index in the current database,
1155    showing statistics about accesses to that specific index. The
1156    <structname>pg_stat_user_indexes</structname> and
1157    <structname>pg_stat_sys_indexes</structname> views
1158    contain the same information,
1159    but filtered to only show user and system indexes respectively.
1160   </para>
1161
1162   <para>
1163    Indexes can be used via either simple index scans or <quote>bitmap</>
1164    index scans.  In a bitmap scan
1165    the output of several indexes can be combined via AND or OR rules,
1166    so it is difficult to associate individual heap row fetches
1167    with specific indexes when a bitmap scan is used.  Therefore, a bitmap
1168    scan increments the
1169    <structname>pg_stat_all_indexes</>.<structfield>idx_tup_read</>
1170    count(s) for the index(es) it uses, and it increments the
1171    <structname>pg_stat_all_tables</>.<structfield>idx_tup_fetch</>
1172    count for the table, but it does not affect
1173    <structname>pg_stat_all_indexes</>.<structfield>idx_tup_fetch</>.
1174   </para>
1175
1176   <note>
1177    <para>
1178     The <structfield>idx_tup_read</> and <structfield>idx_tup_fetch</> counts
1179     can be different even without any use of bitmap scans,
1180     because <structfield>idx_tup_read</> counts
1181     index entries retrieved from the index while <structfield>idx_tup_fetch</>
1182     counts live rows fetched from the table.  The latter will be less if any
1183     dead or not-yet-committed rows are fetched using the index, or if any
1184     heap fetches are avoided by means of an index-only scan.
1185    </para>
1186   </note>
1187
1188   <table id="pg-statio-all-tables-view" xreflabel="pg_statio_all_tables">
1189    <title><structname>pg_statio_all_tables</structname> View</title>
1190    <tgroup cols="3">
1191     <thead>
1192     <row>
1193       <entry>Column</entry>
1194       <entry>Type</entry>
1195       <entry>Description</entry>
1196      </row>
1197     </thead>
1198
1199    <tbody>
1200     <row>
1201      <entry><structfield>relid</></entry>
1202      <entry><type>oid</></entry>
1203      <entry>OID of a table</entry>
1204     </row>
1205     <row>
1206      <entry><structfield>schemaname</></entry>
1207      <entry><type>name</></entry>
1208      <entry>Name of the schema that this table is in</entry>
1209     </row>
1210     <row>
1211      <entry><structfield>relname</></entry>
1212      <entry><type>name</></entry>
1213      <entry>Name of this table</entry>
1214     </row>
1215     <row>
1216      <entry><structfield>heap_blks_read</></entry>
1217      <entry><type>bigint</></entry>
1218      <entry>Number of disk blocks read from this table</entry>
1219     </row>
1220     <row>
1221      <entry><structfield>heap_blks_hit</></entry>
1222      <entry><type>bigint</></entry>
1223      <entry>Number of buffer hits in this table</entry>
1224     </row>
1225     <row>
1226      <entry><structfield>idx_blks_read</></entry>
1227      <entry><type>bigint</></entry>
1228      <entry>Number of disk blocks read from all indexes on this table</entry>
1229     </row>
1230     <row>
1231      <entry><structfield>idx_blks_hit</></entry>
1232      <entry><type>bigint</></entry>
1233      <entry>Number of buffer hits in all indexes on this table</entry>
1234     </row>
1235     <row>
1236      <entry><structfield>toast_blks_read</></entry>
1237      <entry><type>bigint</></entry>
1238      <entry>Number of disk blocks read from this table's TOAST table (if any)</entry>
1239     </row>
1240     <row>
1241      <entry><structfield>toast_blks_hit</></entry>
1242      <entry><type>bigint</></entry>
1243      <entry>Number of buffer hits in this table's TOAST table (if any)</entry>
1244     </row>
1245     <row>
1246      <entry><structfield>tidx_blks_read</></entry>
1247      <entry><type>bigint</></entry>
1248      <entry>Number of disk blocks read from this table's TOAST table indexes (if any)</entry>
1249     </row>
1250     <row>
1251      <entry><structfield>tidx_blks_hit</></entry>
1252      <entry><type>bigint</></entry>
1253      <entry>Number of buffer hits in this table's TOAST table indexes (if any)</entry>
1254     </row>
1255    </tbody>
1256    </tgroup>
1257   </table>
1258
1259   <para>
1260    The <structname>pg_statio_all_tables</structname> view will contain
1261    one row for each table in the current database (including TOAST
1262    tables), showing statistics about I/O on that specific table. The
1263    <structname>pg_statio_user_tables</structname> and
1264    <structname>pg_statio_sys_tables</structname> views
1265    contain the same information,
1266    but filtered to only show user and system tables respectively.
1267   </para>
1268
1269   <table id="pg-statio-all-indexes-view" xreflabel="pg_statio_all_indexes">
1270    <title><structname>pg_statio_all_indexes</structname> View</title>
1271    <tgroup cols="3">
1272     <thead>
1273     <row>
1274       <entry>Column</entry>
1275       <entry>Type</entry>
1276       <entry>Description</entry>
1277      </row>
1278     </thead>
1279
1280    <tbody>
1281     <row>
1282      <entry><structfield>relid</></entry>
1283      <entry><type>oid</></entry>
1284      <entry>OID of the table for this index</entry>
1285     </row>
1286     <row>
1287      <entry><structfield>indexrelid</></entry>
1288      <entry><type>oid</></entry>
1289      <entry>OID of this index</entry>
1290     </row>
1291     <row>
1292      <entry><structfield>schemaname</></entry>
1293      <entry><type>name</></entry>
1294      <entry>Name of the schema this index is in</entry>
1295     </row>
1296     <row>
1297      <entry><structfield>relname</></entry>
1298      <entry><type>name</></entry>
1299      <entry>Name of the table for this index</entry>
1300     </row>
1301     <row>
1302      <entry><structfield>indexrelname</></entry>
1303      <entry><type>name</></entry>
1304      <entry>Name of this index</entry>
1305     </row>
1306     <row>
1307      <entry><structfield>idx_blks_read</></entry>
1308      <entry><type>bigint</></entry>
1309      <entry>Number of disk blocks read from this index</entry>
1310     </row>
1311     <row>
1312      <entry><structfield>idx_blks_hit</></entry>
1313      <entry><type>bigint</></entry>
1314      <entry>Number of buffer hits in this index</entry>
1315     </row>
1316    </tbody>
1317    </tgroup>
1318   </table>
1319
1320   <para>
1321    The <structname>pg_statio_all_indexes</structname> view will contain
1322    one row for each index in the current database,
1323    showing statistics about I/O on that specific index. The
1324    <structname>pg_statio_user_indexes</structname> and
1325    <structname>pg_statio_sys_indexes</structname> views
1326    contain the same information,
1327    but filtered to only show user and system indexes respectively.
1328   </para>
1329
1330   <table id="pg-statio-all-sequences-view" xreflabel="pg_statio_all_sequences">
1331    <title><structname>pg_statio_all_sequences</structname> View</title>
1332    <tgroup cols="3">
1333     <thead>
1334     <row>
1335       <entry>Column</entry>
1336       <entry>Type</entry>
1337       <entry>Description</entry>
1338      </row>
1339     </thead>
1340
1341    <tbody>
1342     <row>
1343      <entry><structfield>relid</></entry>
1344      <entry><type>oid</></entry>
1345      <entry>OID of a sequence</entry>
1346     </row>
1347     <row>
1348      <entry><structfield>schemaname</></entry>
1349      <entry><type>name</></entry>
1350      <entry>Name of the schema this sequence is in</entry>
1351     </row>
1352     <row>
1353      <entry><structfield>relname</></entry>
1354      <entry><type>name</></entry>
1355      <entry>Name of this sequence</entry>
1356     </row>
1357     <row>
1358      <entry><structfield>blks_read</></entry>
1359      <entry><type>bigint</></entry>
1360      <entry>Number of disk blocks read from this sequence</entry>
1361     </row>
1362     <row>
1363      <entry><structfield>blks_hit</></entry>
1364      <entry><type>bigint</></entry>
1365      <entry>Number of buffer hits in this sequence</entry>
1366     </row>
1367    </tbody>
1368    </tgroup>
1369   </table>
1370
1371   <para>
1372    The <structname>pg_statio_all_sequences</structname> view will contain
1373    one row for each sequence in the current database,
1374    showing statistics about I/O on that specific sequence.
1375   </para>
1376
1377   <table id="pg-stat-user-functions-view" xreflabel="pg_stat_user_functions">
1378    <title><structname>pg_stat_user_functions</structname> View</title>
1379    <tgroup cols="3">
1380     <thead>
1381     <row>
1382       <entry>Column</entry>
1383       <entry>Type</entry>
1384       <entry>Description</entry>
1385      </row>
1386     </thead>
1387
1388    <tbody>
1389     <row>
1390      <entry><structfield>funcid</></entry>
1391      <entry><type>oid</></entry>
1392      <entry>OID of a function</entry>
1393     </row>
1394     <row>
1395      <entry><structfield>schemaname</></entry>
1396      <entry><type>name</></entry>
1397      <entry>Name of the schema this function is in</entry>
1398     </row>
1399     <row>
1400      <entry><structfield>funcname</></entry>
1401      <entry><type>name</></entry>
1402      <entry>Name of this function</entry>
1403     </row>
1404     <row>
1405      <entry><structfield>calls</></entry>
1406      <entry><type>bigint</></entry>
1407      <entry>Number of times this function has been called</entry>
1408     </row>
1409     <row>
1410      <entry><structfield>total_time</></entry>
1411      <entry><type>double precision</></entry>
1412      <entry>Total time spent in this function and all other functions
1413      called by it, in milliseconds</entry>
1414     </row>
1415     <row>
1416      <entry><structfield>self_time</></entry>
1417      <entry><type>double precision</></entry>
1418      <entry>Total time spent in this function itself, not including
1419      other functions called by it, in milliseconds</entry>
1420     </row>
1421    </tbody>
1422    </tgroup>
1423   </table>
1424
1425   <para>
1426    The <structname>pg_stat_user_functions</structname> view will contain
1427    one row for each tracked function, showing statistics about executions of
1428    that function.  The <xref linkend="guc-track-functions"> parameter
1429    controls exactly which functions are tracked.
1430   </para>
1431
1432   <table id="pg-stat-replication-view" xreflabel="pg_stat_replication">
1433    <title><structname>pg_stat_replication</structname> View</title>
1434    <tgroup cols="3">
1435     <thead>
1436     <row>
1437       <entry>Column</entry>
1438       <entry>Type</entry>
1439       <entry>Description</entry>
1440      </row>
1441     </thead>
1442
1443    <tbody>
1444     <row>
1445      <entry><structfield>pid</></entry>
1446      <entry><type>integer</></entry>
1447      <entry>Process ID of a WAL sender process</entry>
1448     </row>
1449     <row>
1450      <entry><structfield>usesysid</></entry>
1451      <entry><type>oid</></entry>
1452      <entry>OID of the user logged into this WAL sender process</entry>
1453     </row>
1454     <row>
1455      <entry><structfield>usename</></entry>
1456      <entry><type>name</></entry>
1457      <entry>Name of the user logged into this WAL sender process</entry>
1458     </row>
1459     <row>
1460      <entry><structfield>application_name</></entry>
1461      <entry><type>text</></entry>
1462      <entry>Name of the application that is connected
1463       to this WAL sender</entry>
1464     </row>
1465     <row>
1466      <entry><structfield>client_addr</></entry>
1467      <entry><type>inet</></entry>
1468      <entry>IP address of the client connected to this WAL sender.
1469       If this field is null, it indicates that the client is
1470       connected via a Unix socket on the server machine.
1471      </entry>
1472     </row>
1473     <row>
1474      <entry><structfield>client_hostname</></entry>
1475      <entry><type>text</></entry>
1476      <entry>Host name of the connected client, as reported by a
1477       reverse DNS lookup of <structfield>client_addr</>. This field will
1478       only be non-null for IP connections, and only when <xref
1479       linkend="guc-log-hostname"> is enabled.
1480      </entry>
1481     </row>
1482     <row>
1483      <entry><structfield>client_port</></entry>
1484      <entry><type>integer</></entry>
1485      <entry>TCP port number that the client is using for communication
1486       with this WAL sender, or <literal>-1</> if a Unix socket is used
1487      </entry>
1488     </row>
1489     <row>
1490      <entry><structfield>backend_start</></entry>
1491      <entry><type>timestamp with time zone</></entry>
1492      <entry>Time when this process was started, i.e., when the
1493       client connected to this WAL sender
1494      </entry>
1495     </row>
1496     <row>
1497      <entry><structfield>backend_xid</structfield></entry>
1498      <entry><type>xid</type></entry>
1499      <entry>This standby's <literal>xmin</> horizon reported
1500      by <xref linkend="guc-hot-standby-feedback">.</entry>
1501     </row>
1502     <row>
1503      <entry><structfield>state</></entry>
1504      <entry><type>text</></entry>
1505      <entry>Current WAL sender state</entry>
1506     </row>
1507     <row>
1508      <entry><structfield>sent_location</></entry>
1509      <entry><type>pg_lsn</></entry>
1510      <entry>Last transaction log position sent on this connection</entry>
1511     </row>
1512     <row>
1513      <entry><structfield>write_location</></entry>
1514      <entry><type>pg_lsn</></entry>
1515      <entry>Last transaction log position written to disk by this standby
1516       server</entry>
1517     </row>
1518     <row>
1519      <entry><structfield>flush_location</></entry>
1520      <entry><type>pg_lsn</></entry>
1521      <entry>Last transaction log position flushed to disk by this standby
1522       server</entry>
1523     </row>
1524     <row>
1525      <entry><structfield>replay_location</></entry>
1526      <entry><type>pg_lsn</></entry>
1527      <entry>Last transaction log position replayed into the database on this
1528       standby server</entry>
1529     </row>
1530     <row>
1531      <entry><structfield>sync_priority</></entry>
1532      <entry><type>integer</></entry>
1533      <entry>Priority of this standby server for being chosen as the
1534       synchronous standby</entry>
1535     </row>
1536     <row>
1537      <entry><structfield>sync_state</></entry>
1538      <entry><type>text</></entry>
1539      <entry>Synchronous state of this standby server</entry>
1540     </row>
1541    </tbody>
1542    </tgroup>
1543   </table>
1544
1545   <para>
1546    The <structname>pg_stat_replication</structname> view will contain one row
1547    per WAL sender process, showing statistics about replication to that
1548    sender's connected standby server.  Only directly connected standbys are
1549    listed; no information is available about downstream standby servers.
1550   </para>
1551
1552   <table id="pg-stat-database-conflicts-view" xreflabel="pg_stat_database_conflicts">
1553    <title><structname>pg_stat_database_conflicts</structname> View</title>
1554    <tgroup cols="3">
1555     <thead>
1556     <row>
1557       <entry>Column</entry>
1558       <entry>Type</entry>
1559       <entry>Description</entry>
1560      </row>
1561     </thead>
1562
1563    <tbody>
1564     <row>
1565      <entry><structfield>datid</></entry>
1566      <entry><type>oid</></entry>
1567      <entry>OID of a database</entry>
1568     </row>
1569     <row>
1570      <entry><structfield>datname</></entry>
1571      <entry><type>name</></entry>
1572      <entry>Name of this database</entry>
1573     </row>
1574     <row>
1575      <entry><structfield>confl_tablespace</></entry>
1576      <entry><type>bigint</></entry>
1577      <entry>Number of queries in this database that have been canceled due to
1578       dropped tablespaces</entry>
1579     </row>
1580     <row>
1581      <entry><structfield>confl_lock</></entry>
1582      <entry><type>bigint</></entry>
1583      <entry>Number of queries in this database that have been canceled due to
1584       lock timeouts</entry>
1585     </row>
1586     <row>
1587      <entry><structfield>confl_snapshot</></entry>
1588      <entry><type>bigint</></entry>
1589      <entry>Number of queries in this database that have been canceled due to
1590       old snapshots</entry>
1591     </row>
1592     <row>
1593      <entry><structfield>confl_bufferpin</></entry>
1594      <entry><type>bigint</></entry>
1595      <entry>Number of queries in this database that have been canceled due to
1596       pinned buffers</entry>
1597     </row>
1598     <row>
1599      <entry><structfield>confl_deadlock</></entry>
1600      <entry><type>bigint</></entry>
1601      <entry>Number of queries in this database that have been canceled due to
1602       deadlocks</entry>
1603     </row>
1604    </tbody>
1605    </tgroup>
1606   </table>
1607
1608   <para>
1609    The <structname>pg_stat_database_conflicts</structname> view will contain
1610    one row per database, showing database-wide statistics about
1611    query cancels occurring due to conflicts with recovery on standby servers.
1612    This view will only contain information on standby servers, since
1613    conflicts do not occur on master servers.
1614   </para>
1615
1616  </sect2>
1617
1618  <sect2 id="monitoring-stats-functions">
1619   <title>Statistics Functions</title>
1620
1621   <para>
1622    Other ways of looking at the statistics can be set up by writing
1623    queries that use the same underlying statistics access functions used by
1624    the standard views shown above.  For details such as the functions' names,
1625    consult the definitions of the standard views.  (For example, in
1626    <application>psql</> you could issue <literal>\d+ pg_stat_activity</>.)
1627    The access functions for per-database statistics take a database OID as an
1628    argument to identify which database to report on.
1629    The per-table and per-index functions take a table or index OID.
1630    The functions for per-function statistics take a function OID.
1631    Note that only tables, indexes, and functions in the current database
1632    can be seen with these functions.
1633   </para>
1634
1635   <para>
1636    Additional functions related to statistics collection are listed in <xref
1637    linkend="monitoring-stats-funcs-table">.
1638   </para>
1639
1640   <table id="monitoring-stats-funcs-table">
1641    <title>Additional Statistics Functions</title>
1642
1643    <tgroup cols="3">
1644     <thead>
1645      <row>
1646       <entry>Function</entry>
1647       <entry>Return Type</entry>
1648       <entry>Description</entry>
1649      </row>
1650     </thead>
1651
1652     <tbody>
1653
1654      <row>
1655        <!-- See also the entry for this in func.sgml -->
1656       <entry><literal><function>pg_backend_pid()</function></literal></entry>
1657       <entry><type>integer</type></entry>
1658       <entry>
1659        Process ID of the server process handling the current session
1660       </entry>
1661      </row>
1662
1663      <row>
1664       <entry><literal><function>pg_stat_get_activity</function>(<type>integer</type>)</literal><indexterm><primary>pg_stat_get_activity</primary></indexterm></entry>
1665       <entry><type>setof record</type></entry>
1666       <entry>
1667        Returns a record of information about the backend with the specified PID, or
1668        one record for each active backend in the system if <symbol>NULL</symbol> is
1669        specified. The fields returned are a subset of those in the
1670        <structname>pg_stat_activity</structname> view.
1671       </entry>
1672      </row>
1673
1674      <row>
1675       <entry><literal><function>pg_stat_clear_snapshot()</function></literal><indexterm><primary>pg_stat_clear_snapshot</primary></indexterm></entry>
1676       <entry><type>void</type></entry>
1677       <entry>
1678        Discard the current statistics snapshot
1679       </entry>
1680      </row>
1681
1682      <row>
1683       <entry><literal><function>pg_stat_reset()</function></literal><indexterm><primary>pg_stat_reset</primary></indexterm></entry>
1684       <entry><type>void</type></entry>
1685       <entry>
1686        Reset all statistics counters for the current database to zero
1687        (requires superuser privileges)
1688       </entry>
1689      </row>
1690
1691      <row>
1692       <entry><literal><function>pg_stat_reset_shared</function>(text)</literal><indexterm><primary>pg_stat_reset_shared</primary></indexterm></entry>
1693       <entry><type>void</type></entry>
1694       <entry>
1695        Reset some cluster-wide statistics counters to zero, depending on the
1696        argument (requires superuser privileges).
1697        Calling <literal>pg_stat_reset_shared('bgwriter')</> will zero all the
1698        counters shown in the <structname>pg_stat_bgwriter</> view.
1699        Calling <literal>pg_stat_reset_shared('archiver')</> will zero all the
1700        counters shown in the <structname>pg_stat_archiver</> view.
1701       </entry>
1702      </row>
1703
1704      <row>
1705       <entry><literal><function>pg_stat_reset_single_table_counters</function>(oid)</literal><indexterm><primary>pg_stat_reset_single_table_counters</primary></indexterm></entry>
1706       <entry><type>void</type></entry>
1707       <entry>
1708        Reset statistics for a single table or index in the current database to
1709        zero (requires superuser privileges)
1710       </entry>
1711      </row>
1712
1713      <row>
1714       <entry><literal><function>pg_stat_reset_single_function_counters</function>(oid)</literal><indexterm><primary>pg_stat_reset_single_function_counters</primary></indexterm></entry>
1715       <entry><type>void</type></entry>
1716       <entry>
1717        Reset statistics for a single function in the current database to
1718        zero (requires superuser privileges)
1719       </entry>
1720      </row>
1721     </tbody>
1722    </tgroup>
1723   </table>
1724
1725   <para>
1726    <function>pg_stat_get_activity</function>, the underlying function of
1727    the <structname>pg_stat_activity</> view, returns a set of records
1728    containing all the available information about each backend process.
1729    Sometimes it may be more convenient to obtain just a subset of this
1730    information.  In such cases, an older set of per-backend statistics
1731    access functions can be used; these are shown in <xref
1732    linkend="monitoring-stats-backend-funcs-table">.
1733    These access functions use a backend ID number, which ranges from one
1734    to the number of currently active backends.
1735    The function <function>pg_stat_get_backend_idset</function> provides a
1736    convenient way to generate one row for each active backend for
1737    invoking these functions.  For example, to show the <acronym>PID</>s and
1738    current queries of all backends:
1739
1740 <programlisting>
1741 SELECT pg_stat_get_backend_pid(s.backendid) AS pid,
1742        pg_stat_get_backend_activity(s.backendid) AS query
1743     FROM (SELECT pg_stat_get_backend_idset() AS backendid) AS s;
1744 </programlisting>
1745   </para>
1746
1747   <table id="monitoring-stats-backend-funcs-table">
1748    <title>Per-Backend Statistics Functions</title>
1749
1750    <tgroup cols="3">
1751     <thead>
1752      <row>
1753       <entry>Function</entry>
1754       <entry>Return Type</entry>
1755       <entry>Description</entry>
1756      </row>
1757     </thead>
1758
1759     <tbody>
1760
1761      <row>
1762       <entry><literal><function>pg_stat_get_backend_idset()</function></literal></entry>
1763       <entry><type>setof integer</type></entry>
1764       <entry>Set of currently active backend ID numbers (from 1 to the
1765        number of active backends)</entry>
1766      </row>
1767
1768      <row>
1769       <entry><literal><function>pg_stat_get_backend_activity(integer)</function></literal></entry>
1770       <entry><type>text</type></entry>
1771       <entry>Text of this backend's most recent query</>
1772      </row>
1773
1774      <row>
1775       <entry><literal><function>pg_stat_get_backend_activity_start(integer)</function></literal></entry>
1776       <entry><type>timestamp with time zone</type></entry>
1777       <entry>Time when the most recent query was started</entry>
1778      </row>
1779
1780      <row>
1781       <entry><literal><function>pg_stat_get_backend_client_addr(integer)</function></literal></entry>
1782       <entry><type>inet</type></entry>
1783       <entry>IP address of the client connected to this backend</entry>
1784      </row>
1785
1786      <row>
1787       <entry><literal><function>pg_stat_get_backend_client_port(integer)</function></literal></entry>
1788       <entry><type>integer</type></entry>
1789       <entry>TCP port number that the client is using for communication</entry>
1790      </row>
1791
1792      <row>
1793       <entry><literal><function>pg_stat_get_backend_dbid(integer)</function></literal></entry>
1794       <entry><type>oid</type></entry>
1795       <entry>OID of the database this backend is connected to</entry>
1796      </row>
1797
1798      <row>
1799       <entry><literal><function>pg_stat_get_backend_pid(integer)</function></literal></entry>
1800       <entry><type>integer</type></entry>
1801       <entry>Process ID of this backend</entry>
1802      </row>
1803
1804      <row>
1805       <entry><literal><function>pg_stat_get_backend_start(integer)</function></literal></entry>
1806       <entry><type>timestamp with time zone</type></entry>
1807       <entry>Time when this process was started</entry>
1808      </row>
1809
1810      <row>
1811       <entry><literal><function>pg_stat_get_backend_userid(integer)</function></literal></entry>
1812       <entry><type>oid</type></entry>
1813       <entry>OID of the user logged into this backend</entry>
1814      </row>
1815
1816      <row>
1817       <entry><literal><function>pg_stat_get_backend_waiting(integer)</function></literal></entry>
1818       <entry><type>boolean</type></entry>
1819       <entry>True if this backend is currently waiting on a lock</entry>
1820      </row>
1821
1822      <row>
1823       <entry><literal><function>pg_stat_get_backend_xact_start(integer)</function></literal></entry>
1824       <entry><type>timestamp with time zone</type></entry>
1825       <entry>Time when the current transaction was started</entry>
1826      </row>
1827
1828     </tbody>
1829    </tgroup>
1830   </table>
1831
1832  </sect2>
1833  </sect1>
1834
1835  <sect1 id="monitoring-locks">
1836   <title>Viewing Locks</title>
1837
1838   <indexterm zone="monitoring-locks">
1839    <primary>lock</primary>
1840    <secondary>monitoring</secondary>
1841   </indexterm>
1842
1843   <para>
1844    Another useful tool for monitoring database activity is the
1845    <structname>pg_locks</structname> system table.  It allows the
1846    database administrator to view information about the outstanding
1847    locks in the lock manager. For example, this capability can be used
1848    to:
1849
1850    <itemizedlist>
1851     <listitem>
1852      <para>
1853       View all the locks currently outstanding, all the locks on
1854       relations in a particular database, all the locks on a
1855       particular relation, or all the locks held by a particular
1856       <productname>PostgreSQL</productname> session.
1857      </para>
1858     </listitem>
1859
1860     <listitem>
1861      <para>
1862       Determine the relation in the current database with the most
1863       ungranted locks (which might be a source of contention among
1864       database clients).
1865      </para>
1866     </listitem>
1867
1868     <listitem>
1869      <para>
1870       Determine the effect of lock contention on overall database
1871       performance, as well as the extent to which contention varies
1872       with overall database traffic.
1873      </para>
1874     </listitem>
1875    </itemizedlist>
1876
1877    Details of the <structname>pg_locks</structname> view appear in
1878    <xref linkend="view-pg-locks">.
1879    For more information on locking and managing concurrency with
1880    <productname>PostgreSQL</productname>, refer to <xref linkend="mvcc">.
1881   </para>
1882  </sect1>
1883
1884  <sect1 id="dynamic-trace">
1885   <title>Dynamic Tracing</title>
1886
1887  <indexterm zone="dynamic-trace">
1888   <primary>DTrace</primary>
1889  </indexterm>
1890
1891   <para>
1892    <productname>PostgreSQL</productname> provides facilities to support
1893    dynamic tracing of the database server. This allows an external
1894    utility to be called at specific points in the code and thereby trace
1895    execution.
1896   </para>
1897
1898   <para>
1899    A number of probes or trace points are already inserted into the source
1900    code. These probes are intended to be used by database developers and
1901    administrators. By default the probes are not compiled into
1902    <productname>PostgreSQL</productname>; the user needs to explicitly tell
1903    the configure script to make the probes available.
1904   </para>
1905
1906   <para>
1907    Currently, the
1908    <ulink url="https://en.wikipedia.org/wiki/DTrace">DTrace</ulink>
1909    utility is supported, which, at the time of this writing, is available
1910    on Solaris, Mac OS X, FreeBSD, NetBSD, and Oracle Linux.  The
1911    <ulink url="http://sourceware.org/systemtap/">SystemTap</ulink> project
1912    for Linux provides a DTrace equivalent and can also be used.  Supporting other dynamic
1913    tracing utilities is theoretically possible by changing the definitions for
1914    the macros in <filename>src/include/utils/probes.h</>.
1915   </para>
1916
1917   <sect2 id="compiling-for-trace">
1918    <title>Compiling for Dynamic Tracing</title>
1919
1920   <para>
1921    By default, probes are not available, so you will need to
1922    explicitly tell the configure script to make the probes available
1923    in <productname>PostgreSQL</productname>. To include DTrace support
1924    specify <option>--enable-dtrace</> to configure.  See <xref
1925    linkend="install-procedure"> for further information.
1926   </para>
1927   </sect2>
1928
1929   <sect2 id="trace-points">
1930    <title>Built-in Probes</title>
1931
1932   <para>
1933    A number of standard probes are provided in the source code,
1934    as shown in <xref linkend="dtrace-probe-point-table">;
1935    <xref linkend="typedefs-table">
1936    shows the types used in the probes.  More probes can certainly be
1937    added to enhance <productname>PostgreSQL</>'s observability.
1938   </para>
1939
1940  <table id="dtrace-probe-point-table">
1941   <title>Built-in DTrace Probes</title>
1942   <tgroup cols="3">
1943    <thead>
1944     <row>
1945      <entry>Name</entry>
1946      <entry>Parameters</entry>
1947      <entry>Description</entry>
1948     </row>
1949    </thead>
1950
1951    <tbody>
1952
1953     <row>
1954      <entry>transaction-start</entry>
1955      <entry>(LocalTransactionId)</entry>
1956      <entry>Probe that fires at the start of a new transaction.
1957       arg0 is the transaction ID.</entry>
1958     </row>
1959     <row>
1960      <entry>transaction-commit</entry>
1961      <entry>(LocalTransactionId)</entry>
1962      <entry>Probe that fires when a transaction completes successfully.
1963       arg0 is the transaction ID.</entry>
1964     </row>
1965     <row>
1966      <entry>transaction-abort</entry>
1967      <entry>(LocalTransactionId)</entry>
1968      <entry>Probe that fires when a transaction completes unsuccessfully.
1969       arg0 is the transaction ID.</entry>
1970     </row>
1971     <row>
1972      <entry>query-start</entry>
1973      <entry>(const char *)</entry>
1974      <entry>Probe that fires when the processing of a query is started.
1975       arg0 is the query string.</entry>
1976     </row>
1977     <row>
1978      <entry>query-done</entry>
1979      <entry>(const char *)</entry>
1980      <entry>Probe that fires when the processing of a query is complete.
1981       arg0 is the query string.</entry>
1982     </row>
1983     <row>
1984      <entry>query-parse-start</entry>
1985      <entry>(const char *)</entry>
1986      <entry>Probe that fires when the parsing of a query is started.
1987       arg0 is the query string.</entry>
1988     </row>
1989     <row>
1990      <entry>query-parse-done</entry>
1991      <entry>(const char *)</entry>
1992      <entry>Probe that fires when the parsing of a query is complete.
1993       arg0 is the query string.</entry>
1994     </row>
1995     <row>
1996      <entry>query-rewrite-start</entry>
1997      <entry>(const char *)</entry>
1998      <entry>Probe that fires when the rewriting of a query is started.
1999       arg0 is the query string.</entry>
2000     </row>
2001     <row>
2002      <entry>query-rewrite-done</entry>
2003      <entry>(const char *)</entry>
2004      <entry>Probe that fires when the rewriting of a query is complete.
2005       arg0 is the query string.</entry>
2006     </row>
2007     <row>
2008      <entry>query-plan-start</entry>
2009      <entry>()</entry>
2010      <entry>Probe that fires when the planning of a query is started.</entry>
2011     </row>
2012     <row>
2013      <entry>query-plan-done</entry>
2014      <entry>()</entry>
2015      <entry>Probe that fires when the planning of a query is complete.</entry>
2016     </row>
2017     <row>
2018      <entry>query-execute-start</entry>
2019      <entry>()</entry>
2020      <entry>Probe that fires when the execution of a query is started.</entry>
2021     </row>
2022     <row>
2023      <entry>query-execute-done</entry>
2024      <entry>()</entry>
2025      <entry>Probe that fires when the execution of a query is complete.</entry>
2026     </row>
2027     <row>
2028      <entry>statement-status</entry>
2029      <entry>(const char *)</entry>
2030      <entry>Probe that fires anytime the server process updates its
2031       <structname>pg_stat_activity</>.<structfield>status</>.
2032       arg0 is the new status string.</entry>
2033     </row>
2034     <row>
2035      <entry>checkpoint-start</entry>
2036      <entry>(int)</entry>
2037      <entry>Probe that fires when a checkpoint is started.
2038       arg0 holds the bitwise flags used to distinguish different checkpoint
2039       types, such as shutdown, immediate or force.</entry>
2040     </row>
2041     <row>
2042      <entry>checkpoint-done</entry>
2043      <entry>(int, int, int, int, int)</entry>
2044      <entry>Probe that fires when a checkpoint is complete.
2045       (The probes listed next fire in sequence during checkpoint processing.)
2046       arg0 is the number of buffers written. arg1 is the total number of
2047       buffers. arg2, arg3 and arg4 contain the number of xlog file(s) added,
2048       removed and recycled respectively.</entry>
2049     </row>
2050     <row>
2051      <entry>clog-checkpoint-start</entry>
2052      <entry>(bool)</entry>
2053      <entry>Probe that fires when the CLOG portion of a checkpoint is started.
2054       arg0 is true for normal checkpoint, false for shutdown
2055       checkpoint.</entry>
2056     </row>
2057     <row>
2058      <entry>clog-checkpoint-done</entry>
2059      <entry>(bool)</entry>
2060      <entry>Probe that fires when the CLOG portion of a checkpoint is
2061       complete. arg0 has the same meaning as for clog-checkpoint-start.</entry>
2062     </row>
2063     <row>
2064      <entry>subtrans-checkpoint-start</entry>
2065      <entry>(bool)</entry>
2066      <entry>Probe that fires when the SUBTRANS portion of a checkpoint is
2067       started.
2068       arg0 is true for normal checkpoint, false for shutdown
2069       checkpoint.</entry>
2070     </row>
2071     <row>
2072      <entry>subtrans-checkpoint-done</entry>
2073      <entry>(bool)</entry>
2074      <entry>Probe that fires when the SUBTRANS portion of a checkpoint is
2075       complete. arg0 has the same meaning as for
2076       subtrans-checkpoint-start.</entry>
2077     </row>
2078     <row>
2079      <entry>multixact-checkpoint-start</entry>
2080      <entry>(bool)</entry>
2081      <entry>Probe that fires when the MultiXact portion of a checkpoint is
2082       started.
2083       arg0 is true for normal checkpoint, false for shutdown
2084       checkpoint.</entry>
2085     </row>
2086     <row>
2087      <entry>multixact-checkpoint-done</entry>
2088      <entry>(bool)</entry>
2089      <entry>Probe that fires when the MultiXact portion of a checkpoint is
2090       complete. arg0 has the same meaning as for
2091       multixact-checkpoint-start.</entry>
2092     </row>
2093     <row>
2094      <entry>buffer-checkpoint-start</entry>
2095      <entry>(int)</entry>
2096      <entry>Probe that fires when the buffer-writing portion of a checkpoint
2097       is started.
2098       arg0 holds the bitwise flags used to distinguish different checkpoint
2099       types, such as shutdown, immediate or force.</entry>
2100     </row>
2101     <row>
2102      <entry>buffer-sync-start</entry>
2103      <entry>(int, int)</entry>
2104      <entry>Probe that fires when we begin to write dirty buffers during
2105       checkpoint (after identifying which buffers must be written).
2106       arg0 is the total number of buffers.
2107       arg1 is the number that are currently dirty and need to be written.</entry>
2108     </row>
2109     <row>
2110      <entry>buffer-sync-written</entry>
2111      <entry>(int)</entry>
2112      <entry>Probe that fires after each buffer is written during checkpoint.
2113       arg0 is the ID number of the buffer.</entry>
2114     </row>
2115     <row>
2116      <entry>buffer-sync-done</entry>
2117      <entry>(int, int, int)</entry>
2118      <entry>Probe that fires when all dirty buffers have been written.
2119       arg0 is the total number of buffers.
2120       arg1 is the number of buffers actually written by the checkpoint process.
2121       arg2 is the number that were expected to be written (arg1 of
2122       buffer-sync-start); any difference reflects other processes flushing
2123       buffers during the checkpoint.</entry>
2124     </row>
2125     <row>
2126      <entry>buffer-checkpoint-sync-start</entry>
2127      <entry>()</entry>
2128      <entry>Probe that fires after dirty buffers have been written to the
2129       kernel, and before starting to issue fsync requests.</entry>
2130     </row>
2131     <row>
2132      <entry>buffer-checkpoint-done</entry>
2133      <entry>()</entry>
2134      <entry>Probe that fires when syncing of buffers to disk is
2135       complete.</entry>
2136     </row>
2137     <row>
2138      <entry>twophase-checkpoint-start</entry>
2139      <entry>()</entry>
2140      <entry>Probe that fires when the two-phase portion of a checkpoint is
2141       started.</entry>
2142     </row>
2143     <row>
2144      <entry>twophase-checkpoint-done</entry>
2145      <entry>()</entry>
2146      <entry>Probe that fires when the two-phase portion of a checkpoint is
2147       complete.</entry>
2148     </row>
2149     <row>
2150      <entry>buffer-read-start</entry>
2151      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid, int, bool)</entry>
2152      <entry>Probe that fires when a buffer read is started.
2153       arg0 and arg1 contain the fork and block numbers of the page (but
2154       arg1 will be -1 if this is a relation extension request).
2155       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
2156       identifying the relation.
2157       arg5 is the ID of the backend which created the temporary relation for a
2158       local buffer, or InvalidBackendId (-1) for a shared buffer.
2159       arg6 is true for a relation extension request, false for normal
2160       read.</entry>
2161     </row>
2162     <row>
2163      <entry>buffer-read-done</entry>
2164      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid, int, bool, bool)</entry>
2165      <entry>Probe that fires when a buffer read is complete.
2166       arg0 and arg1 contain the fork and block numbers of the page (if this
2167       is a relation extension request, arg1 now contains the block number
2168       of the newly added block).
2169       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
2170       identifying the relation.
2171       arg5 is the ID of the backend which created the temporary relation for a
2172       local buffer, or InvalidBackendId (-1) for a shared buffer.
2173       arg6 is true for a relation extension request, false for normal
2174       read.
2175       arg7 is true if the buffer was found in the pool, false if not.</entry>
2176     </row>
2177     <row>
2178      <entry>buffer-flush-start</entry>
2179      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid)</entry>
2180      <entry>Probe that fires before issuing any write request for a shared
2181       buffer.
2182       arg0 and arg1 contain the fork and block numbers of the page.
2183       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
2184       identifying the relation.</entry>
2185     </row>
2186     <row>
2187      <entry>buffer-flush-done</entry>
2188      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid)</entry>
2189      <entry>Probe that fires when a write request is complete.  (Note
2190       that this just reflects the time to pass the data to the kernel;
2191       it's typically not actually been written to disk yet.)
2192       The arguments are the same as for buffer-flush-start.</entry>
2193     </row>
2194     <row>
2195      <entry>buffer-write-dirty-start</entry>
2196      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid)</entry>
2197      <entry>Probe that fires when a server process begins to write a dirty
2198       buffer.  (If this happens often, it implies that
2199       <xref linkend="guc-shared-buffers"> is too
2200       small or the bgwriter control parameters need adjustment.)
2201       arg0 and arg1 contain the fork and block numbers of the page.
2202       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
2203       identifying the relation.</entry>
2204     </row>
2205     <row>
2206      <entry>buffer-write-dirty-done</entry>
2207      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid)</entry>
2208      <entry>Probe that fires when a dirty-buffer write is complete.
2209       The arguments are the same as for buffer-write-dirty-start.</entry>
2210     </row>
2211     <row>
2212      <entry>wal-buffer-write-dirty-start</entry>
2213      <entry>()</entry>
2214      <entry>Probe that fires when a server process begins to write a
2215       dirty WAL buffer because no more WAL buffer space is available.
2216       (If this happens often, it implies that
2217       <xref linkend="guc-wal-buffers"> is too small.)</entry>
2218     </row>
2219     <row>
2220      <entry>wal-buffer-write-dirty-done</entry>
2221      <entry>()</entry>
2222      <entry>Probe that fires when a dirty WAL buffer write is complete.</entry>
2223     </row>
2224     <row>
2225      <entry>xlog-insert</entry>
2226      <entry>(unsigned char, unsigned char)</entry>
2227      <entry>Probe that fires when a WAL record is inserted.
2228       arg0 is the resource manager (rmid) for the record.
2229       arg1 contains the info flags.</entry>
2230     </row>
2231     <row>
2232      <entry>xlog-switch</entry>
2233      <entry>()</entry>
2234      <entry>Probe that fires when a WAL segment switch is requested.</entry>
2235     </row>
2236     <row>
2237      <entry>smgr-md-read-start</entry>
2238      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</entry>
2239      <entry>Probe that fires when beginning to read a block from a relation.
2240       arg0 and arg1 contain the fork and block numbers of the page.
2241       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
2242       identifying the relation.
2243       arg5 is the ID of the backend which created the temporary relation for a
2244       local buffer, or InvalidBackendId (-1) for a shared buffer.</entry>
2245     </row>
2246     <row>
2247      <entry>smgr-md-read-done</entry>
2248      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)</entry>
2249      <entry>Probe that fires when a block read is complete.
2250       arg0 and arg1 contain the fork and block numbers of the page.
2251       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
2252       identifying the relation.
2253       arg5 is the ID of the backend which created the temporary relation for a
2254       local buffer, or InvalidBackendId (-1) for a shared buffer.
2255       arg6 is the number of bytes actually read, while arg7 is the number
2256       requested (if these are different it indicates trouble).</entry>
2257     </row>
2258     <row>
2259      <entry>smgr-md-write-start</entry>
2260      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</entry>
2261      <entry>Probe that fires when beginning to write a block to a relation.
2262       arg0 and arg1 contain the fork and block numbers of the page.
2263       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
2264       identifying the relation.
2265       arg5 is the ID of the backend which created the temporary relation for a
2266       local buffer, or InvalidBackendId (-1) for a shared buffer.</entry>
2267     </row>
2268     <row>
2269      <entry>smgr-md-write-done</entry>
2270      <entry>(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)</entry>
2271      <entry>Probe that fires when a block write is complete.
2272       arg0 and arg1 contain the fork and block numbers of the page.
2273       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
2274       identifying the relation.
2275       arg5 is the ID of the backend which created the temporary relation for a
2276       local buffer, or InvalidBackendId (-1) for a shared buffer.
2277       arg6 is the number of bytes actually written, while arg7 is the number
2278       requested (if these are different it indicates trouble).</entry>
2279     </row>
2280     <row>
2281      <entry>sort-start</entry>
2282      <entry>(int, bool, int, int, bool)</entry>
2283      <entry>Probe that fires when a sort operation is started.
2284       arg0 indicates heap, index or datum sort.
2285       arg1 is true for unique-value enforcement.
2286       arg2 is the number of key columns.
2287       arg3 is the number of kilobytes of work memory allowed.
2288       arg4 is true if random access to the sort result is required.</entry>
2289     </row>
2290     <row>
2291      <entry>sort-done</entry>
2292      <entry>(bool, long)</entry>
2293      <entry>Probe that fires when a sort is complete.
2294       arg0 is true for external sort, false for internal sort.
2295       arg1 is the number of disk blocks used for an external sort,
2296       or kilobytes of memory used for an internal sort.</entry>
2297     </row>
2298     <row>
2299      <entry>lwlock-acquire</entry>
2300      <entry>(char *, int, LWLockMode)</entry>
2301      <entry>Probe that fires when an LWLock has been acquired.
2302       arg0 is the LWLock's tranche.
2303       arg1 is the LWLock's offset within its tranche.
2304       arg2 is the requested lock mode, either exclusive or shared.</entry>
2305     </row>
2306     <row>
2307      <entry>lwlock-release</entry>
2308      <entry>(char *, int)</entry>
2309      <entry>Probe that fires when an LWLock has been released (but note
2310       that any released waiters have not yet been awakened).
2311       arg0 is the LWLock's tranche.
2312       arg1 is the LWLock's offset within its tranche.</entry>
2313     </row>
2314     <row>
2315      <entry>lwlock-wait-start</entry>
2316      <entry>(char *, int, LWLockMode)</entry>
2317      <entry>Probe that fires when an LWLock was not immediately available and
2318       a server process has begun to wait for the lock to become available.
2319       arg0 is the LWLock's tranche.
2320       arg1 is the LWLock's offset within its tranche.
2321       arg2 is the requested lock mode, either exclusive or shared.</entry>
2322     </row>
2323     <row>
2324      <entry>lwlock-wait-done</entry>
2325      <entry>(char *, int, LWLockMode)</entry>
2326      <entry>Probe that fires when a server process has been released from its
2327       wait for an LWLock (it does not actually have the lock yet).
2328       arg0 is the LWLock's tranche.
2329       arg1 is the LWLock's offset within its tranche.
2330       arg2 is the requested lock mode, either exclusive or shared.</entry>
2331     </row>
2332     <row>
2333      <entry>lwlock-condacquire</entry>
2334      <entry>(char *, int, LWLockMode)</entry>
2335      <entry>Probe that fires when an LWLock was successfully acquired when the
2336       caller specified no waiting.
2337       arg0 is the LWLock's tranche.
2338       arg1 is the LWLock's offset within its tranche.
2339       arg2 is the requested lock mode, either exclusive or shared.</entry>
2340     </row>
2341     <row>
2342      <entry>lwlock-condacquire-fail</entry>
2343      <entry>(char *, int, LWLockMode)</entry>
2344      <entry>Probe that fires when an LWLock was not successfully acquired when
2345       the caller specified no waiting.
2346       arg0 is the LWLock's tranche.
2347       arg1 is the LWLock's offset within its tranche.
2348       arg2 is the requested lock mode, either exclusive or shared.</entry>
2349     </row>
2350     <row>
2351      <entry>lock-wait-start</entry>
2352      <entry>(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)</entry>
2353      <entry>Probe that fires when a request for a heavyweight lock (lmgr lock)
2354       has begun to wait because the lock is not available.
2355       arg0 through arg3 are the tag fields identifying the object being
2356       locked.  arg4 indicates the type of object being locked.
2357       arg5 indicates the lock type being requested.</entry>
2358     </row>
2359     <row>
2360      <entry>lock-wait-done</entry>
2361      <entry>(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)</entry>
2362      <entry>Probe that fires when a request for a heavyweight lock (lmgr lock)
2363       has finished waiting (i.e., has acquired the lock).
2364       The arguments are the same as for lock-wait-start.</entry>
2365     </row>
2366     <row>
2367      <entry>deadlock-found</entry>
2368      <entry>()</entry>
2369      <entry>Probe that fires when a deadlock is found by the deadlock
2370       detector.</entry>
2371     </row>
2372
2373    </tbody>
2374    </tgroup>
2375   </table>
2376
2377  <table id="typedefs-table">
2378   <title>Defined Types Used in Probe Parameters</title>
2379   <tgroup cols="2">
2380    <thead>
2381     <row>
2382      <entry>Type</entry>
2383      <entry>Definition</entry>
2384     </row>
2385    </thead>
2386
2387    <tbody>
2388
2389     <row>
2390      <entry>LocalTransactionId</entry>
2391      <entry>unsigned int</entry>
2392     </row>
2393     <row>
2394      <entry>LWLockMode</entry>
2395      <entry>int</entry>
2396     </row>
2397     <row>
2398      <entry>LOCKMODE</entry>
2399      <entry>int</entry>
2400     </row>
2401     <row>
2402      <entry>BlockNumber</entry>
2403      <entry>unsigned int</entry>
2404     </row>
2405     <row>
2406      <entry>Oid</entry>
2407      <entry>unsigned int</entry>
2408     </row>
2409     <row>
2410      <entry>ForkNumber</entry>
2411      <entry>int</entry>
2412     </row>
2413     <row>
2414      <entry>bool</entry>
2415      <entry>char</entry>
2416     </row>
2417
2418    </tbody>
2419    </tgroup>
2420   </table>
2421
2422
2423   </sect2>
2424
2425   <sect2 id="using-trace-points">
2426    <title>Using Probes</title>
2427
2428   <para>
2429    The example below shows a DTrace script for analyzing transaction
2430    counts in the system, as an alternative to snapshotting
2431    <structname>pg_stat_database</> before and after a performance test:
2432 <programlisting>
2433 #!/usr/sbin/dtrace -qs
2434
2435 postgresql$1:::transaction-start
2436 {
2437       @start["Start"] = count();
2438       self->ts  = timestamp;
2439 }
2440
2441 postgresql$1:::transaction-abort
2442 {
2443       @abort["Abort"] = count();
2444 }
2445
2446 postgresql$1:::transaction-commit
2447 /self->ts/
2448 {
2449       @commit["Commit"] = count();
2450       @time["Total time (ns)"] = sum(timestamp - self->ts);
2451       self->ts=0;
2452 }
2453 </programlisting>
2454    When executed, the example D script gives output such as:
2455 <screen>
2456 # ./txn_count.d `pgrep -n postgres` or ./txn_count.d &lt;PID&gt;
2457 ^C
2458
2459 Start                                          71
2460 Commit                                         70
2461 Total time (ns)                        2312105013
2462 </screen>
2463   </para>
2464
2465   <note>
2466    <para>
2467     SystemTap uses a different notation for trace scripts than DTrace does,
2468     even though the underlying trace points are compatible.  One point worth
2469     noting is that at this writing, SystemTap scripts must reference probe
2470     names using double underscores in place of hyphens.  This is expected to
2471     be fixed in future SystemTap releases.
2472    </para>
2473   </note>
2474
2475   <para>
2476    You should remember that DTrace scripts need to be carefully written and
2477    debugged, otherwise the trace information collected might
2478    be meaningless. In most cases where problems are found it is the
2479    instrumentation that is at fault, not the underlying system. When
2480    discussing information found using dynamic tracing, be sure to enclose
2481    the script used to allow that too to be checked and discussed.
2482   </para>
2483
2484   <para>
2485    More example scripts can be found in the PgFoundry
2486    <ulink url="http://pgfoundry.org/projects/dtrace/">dtrace project</ulink>.
2487   </para>
2488   </sect2>
2489
2490   <sect2 id="defining-trace-points">
2491    <title>Defining New Probes</title>
2492
2493   <para>
2494    New probes can be defined within the code wherever the developer
2495    desires, though this will require a recompilation. Below are the steps
2496    for inserting new probes:
2497   </para>
2498
2499   <procedure>
2500    <step>
2501     <para>
2502      Decide on probe names and data to be made available through the probes
2503     </para>
2504    </step>
2505
2506    <step>
2507     <para>
2508      Add the probe definitions to <filename>src/backend/utils/probes.d</>
2509     </para>
2510    </step>
2511
2512    <step>
2513     <para>
2514      Include <filename>pg_trace.h</> if it is not already present in the
2515      module(s) containing the probe points, and insert
2516      <literal>TRACE_POSTGRESQL</> probe macros at the desired locations
2517      in the source code
2518     </para>
2519    </step>
2520
2521    <step>
2522     <para>
2523      Recompile and verify that the new probes are available
2524     </para>
2525    </step>
2526   </procedure>
2527
2528   <formalpara>
2529    <title>Example:</title>
2530    <para>
2531     Here is an example of how you would add a probe to trace all new
2532     transactions by transaction ID.
2533    </para>
2534   </formalpara>
2535
2536   <procedure>
2537    <step>
2538     <para>
2539      Decide that the probe will be named <literal>transaction-start</> and
2540      requires a parameter of type LocalTransactionId
2541     </para>
2542    </step>
2543
2544    <step>
2545     <para>
2546      Add the probe definition to <filename>src/backend/utils/probes.d</>:
2547 <programlisting>
2548 probe transaction__start(LocalTransactionId);
2549 </programlisting>
2550      Note the use of the double underline in the probe name. In a DTrace
2551      script using the probe, the double underline needs to be replaced with a
2552      hyphen, so <literal>transaction-start</> is the name to document for
2553      users.
2554     </para>
2555    </step>
2556
2557    <step>
2558     <para>
2559      At compile time, <literal>transaction__start</> is converted to a macro
2560      called <literal>TRACE_POSTGRESQL_TRANSACTION_START</> (notice the
2561      underscores are single here), which is available by including
2562      <filename>pg_trace.h</>.  Add the macro call to the appropriate location
2563      in the source code.  In this case, it looks like the following:
2564
2565 <programlisting>
2566 TRACE_POSTGRESQL_TRANSACTION_START(vxid.localTransactionId);
2567 </programlisting>
2568     </para>
2569    </step>
2570
2571    <step>
2572     <para>
2573      After recompiling and running the new binary, check that your newly added
2574      probe is available by executing the following DTrace command.  You
2575      should see similar output:
2576 <screen>
2577 # dtrace -ln transaction-start
2578    ID    PROVIDER          MODULE           FUNCTION NAME
2579 18705 postgresql49878     postgres     StartTransactionCommand transaction-start
2580 18755 postgresql49877     postgres     StartTransactionCommand transaction-start
2581 18805 postgresql49876     postgres     StartTransactionCommand transaction-start
2582 18855 postgresql49875     postgres     StartTransactionCommand transaction-start
2583 18986 postgresql49873     postgres     StartTransactionCommand transaction-start
2584 </screen>
2585     </para>
2586    </step>
2587   </procedure>
2588
2589   <para>
2590    There are a few things to be careful about when adding trace macros
2591    to the C code:
2592
2593    <itemizedlist>
2594     <listitem>
2595      <para>
2596       You should take care that the data types specified for a probe's
2597       parameters match the data types of the variables used in the macro.
2598       Otherwise, you will get compilation errors.
2599      </para>
2600     </listitem>
2601
2602
2603     <listitem>
2604      <para>
2605       On most platforms, if <productname>PostgreSQL</productname> is
2606       built with <option>--enable-dtrace</>, the arguments to a trace
2607       macro will be evaluated whenever control passes through the
2608       macro, <emphasis>even if no tracing is being done</>.  This is
2609       usually not worth worrying about if you are just reporting the
2610       values of a few local variables.  But beware of putting expensive
2611       function calls into the arguments.  If you need to do that,
2612       consider protecting the macro with a check to see if the trace
2613       is actually enabled:
2614
2615 <programlisting>
2616 if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED())
2617     TRACE_POSTGRESQL_TRANSACTION_START(some_function(...));
2618 </programlisting>
2619
2620       Each trace macro has a corresponding <literal>ENABLED</> macro.
2621      </para>
2622     </listitem>
2623    </itemizedlist>
2624
2625   </para>
2626
2627   </sect2>
2628
2629  </sect1>
2630
2631 </chapter>