begriffs open source - ai-pg/blob - full-docs/html/dynamic-trace.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>27.5. Dynamic Tracing</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="progress-reporting.html" title="27.4. Progress Reporting" /><link rel="next" href="diskusage.html" title="27.6. Monitoring Disk Usage" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">27.5. Dynamic Tracing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="progress-reporting.html" title="27.4. Progress Reporting">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="monitoring.html" title="Chapter 27. Monitoring Database Activity">Up</a></td><th width="60%" align="center">Chapter 27. Monitoring Database Activity</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="diskusage.html" title="27.6. Monitoring Disk Usage">Next</a></td></tr></table><hr /></div><div class="sect1" id="DYNAMIC-TRACE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">27.5. Dynamic Tracing <a href="#DYNAMIC-TRACE" class="id_link">#</a></h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="dynamic-trace.html#COMPILING-FOR-TRACE">27.5.1. Compiling for Dynamic Tracing</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#TRACE-POINTS">27.5.2. Built-in Probes</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#USING-TRACE-POINTS">27.5.3. Using Probes</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#DEFINING-TRACE-POINTS">27.5.4. Defining New Probes</a></span></dt></dl></div><a id="id-1.6.14.10.2" class="indexterm"></a><p>
   3    <span class="productname">PostgreSQL</span> provides facilities to support
   4    dynamic tracing of the database server. This allows an external
   5    utility to be called at specific points in the code and thereby trace
   6    execution.
   7   </p><p>
   8    A number of probes or trace points are already inserted into the source
   9    code. These probes are intended to be used by database developers and
  10    administrators. By default the probes are not compiled into
  11    <span class="productname">PostgreSQL</span>; the user needs to explicitly tell
  12    the configure script to make the probes available.
  13   </p><p>
  14    Currently, the
  15    <a class="ulink" href="https://en.wikipedia.org/wiki/DTrace" target="_top">DTrace</a>
  16    utility is supported, which, at the time of this writing, is available
  17    on Solaris, macOS, FreeBSD, NetBSD, and Oracle Linux.  The
  18    <a class="ulink" href="https://sourceware.org/systemtap/" target="_top">SystemTap</a> project
  19    for Linux provides a DTrace equivalent and can also be used.  Supporting other dynamic
  20    tracing utilities is theoretically possible by changing the definitions for
  21    the macros in <code class="filename">src/include/utils/probes.h</code>.
  22   </p><div class="sect2" id="COMPILING-FOR-TRACE"><div class="titlepage"><div><div><h3 class="title">27.5.1. Compiling for Dynamic Tracing <a href="#COMPILING-FOR-TRACE" class="id_link">#</a></h3></div></div></div><p>
  23    By default, probes are not available, so you will need to
  24    explicitly tell the configure script to make the probes available
  25    in <span class="productname">PostgreSQL</span>. To include DTrace support
  26    specify <code class="option">--enable-dtrace</code> to configure.  See <a class="xref" href="install-make.html#CONFIGURE-OPTIONS-DEVEL" title="17.3.3.6. Developer Options">Section 17.3.3.6</a> for further information.
  27   </p></div><div class="sect2" id="TRACE-POINTS"><div class="titlepage"><div><div><h3 class="title">27.5.2. Built-in Probes <a href="#TRACE-POINTS" class="id_link">#</a></h3></div></div></div><p>
  28    A number of standard probes are provided in the source code,
  29    as shown in <a class="xref" href="dynamic-trace.html#DTRACE-PROBE-POINT-TABLE" title="Table 27.49. Built-in DTrace Probes">Table 27.49</a>;
  30    <a class="xref" href="dynamic-trace.html#TYPEDEFS-TABLE" title="Table 27.50. Defined Types Used in Probe Parameters">Table 27.50</a>
  31    shows the types used in the probes.  More probes can certainly be
  32    added to enhance <span class="productname">PostgreSQL</span>'s observability.
  33   </p><div class="table" id="DTRACE-PROBE-POINT-TABLE"><p class="title"><strong>Table 27.49. Built-in DTrace Probes</strong></p><div class="table-contents"><table class="table" summary="Built-in DTrace Probes" border="1"><colgroup><col class="col1" /><col class="col2" /><col class="col3" /></colgroup><thead><tr><th>Name</th><th>Parameters</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">transaction-start</code></td><td><code class="literal">(LocalTransactionId)</code></td><td>Probe that fires at the start of a new transaction.
  34       arg0 is the transaction ID.</td></tr><tr><td><code class="literal">transaction-commit</code></td><td><code class="literal">(LocalTransactionId)</code></td><td>Probe that fires when a transaction completes successfully.
  35       arg0 is the transaction ID.</td></tr><tr><td><code class="literal">transaction-abort</code></td><td><code class="literal">(LocalTransactionId)</code></td><td>Probe that fires when a transaction completes unsuccessfully.
  36       arg0 is the transaction ID.</td></tr><tr><td><code class="literal">query-start</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the processing of a query is started.
  37       arg0 is the query string.</td></tr><tr><td><code class="literal">query-done</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the processing of a query is complete.
  38       arg0 is the query string.</td></tr><tr><td><code class="literal">query-parse-start</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the parsing of a query is started.
  39       arg0 is the query string.</td></tr><tr><td><code class="literal">query-parse-done</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the parsing of a query is complete.
  40       arg0 is the query string.</td></tr><tr><td><code class="literal">query-rewrite-start</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the rewriting of a query is started.
  41       arg0 is the query string.</td></tr><tr><td><code class="literal">query-rewrite-done</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires when the rewriting of a query is complete.
  42       arg0 is the query string.</td></tr><tr><td><code class="literal">query-plan-start</code></td><td><code class="literal">()</code></td><td>Probe that fires when the planning of a query is started.</td></tr><tr><td><code class="literal">query-plan-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when the planning of a query is complete.</td></tr><tr><td><code class="literal">query-execute-start</code></td><td><code class="literal">()</code></td><td>Probe that fires when the execution of a query is started.</td></tr><tr><td><code class="literal">query-execute-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when the execution of a query is complete.</td></tr><tr><td><code class="literal">statement-status</code></td><td><code class="literal">(const char *)</code></td><td>Probe that fires anytime the server process updates its
  43       <code class="structname">pg_stat_activity</code>.<code class="structfield">status</code>.
  44       arg0 is the new status string.</td></tr><tr><td><code class="literal">checkpoint-start</code></td><td><code class="literal">(int)</code></td><td>Probe that fires when a checkpoint is started.
  45       arg0 holds the bitwise flags used to distinguish different checkpoint
  46       types, such as shutdown, immediate or force.</td></tr><tr><td><code class="literal">checkpoint-done</code></td><td><code class="literal">(int, int, int, int, int)</code></td><td>Probe that fires when a checkpoint is complete.
  47       (The probes listed next fire in sequence during checkpoint processing.)
  48       arg0 is the number of buffers written. arg1 is the total number of
  49       buffers. arg2, arg3 and arg4 contain the number of WAL files added,
  50       removed and recycled respectively.</td></tr><tr><td><code class="literal">clog-checkpoint-start</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the CLOG portion of a checkpoint is started.
  51       arg0 is true for normal checkpoint, false for shutdown
  52       checkpoint.</td></tr><tr><td><code class="literal">clog-checkpoint-done</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the CLOG portion of a checkpoint is
  53       complete. arg0 has the same meaning as for <code class="literal">clog-checkpoint-start</code>.</td></tr><tr><td><code class="literal">subtrans-checkpoint-start</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the SUBTRANS portion of a checkpoint is
  54       started.
  55       arg0 is true for normal checkpoint, false for shutdown
  56       checkpoint.</td></tr><tr><td><code class="literal">subtrans-checkpoint-done</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the SUBTRANS portion of a checkpoint is
  57       complete. arg0 has the same meaning as for
  58       <code class="literal">subtrans-checkpoint-start</code>.</td></tr><tr><td><code class="literal">multixact-checkpoint-start</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the MultiXact portion of a checkpoint is
  59       started.
  60       arg0 is true for normal checkpoint, false for shutdown
  61       checkpoint.</td></tr><tr><td><code class="literal">multixact-checkpoint-done</code></td><td><code class="literal">(bool)</code></td><td>Probe that fires when the MultiXact portion of a checkpoint is
  62       complete. arg0 has the same meaning as for
  63       <code class="literal">multixact-checkpoint-start</code>.</td></tr><tr><td><code class="literal">buffer-checkpoint-start</code></td><td><code class="literal">(int)</code></td><td>Probe that fires when the buffer-writing portion of a checkpoint
  64       is started.
  65       arg0 holds the bitwise flags used to distinguish different checkpoint
  66       types, such as shutdown, immediate or force.</td></tr><tr><td><code class="literal">buffer-sync-start</code></td><td><code class="literal">(int, int)</code></td><td>Probe that fires when we begin to write dirty buffers during
  67       checkpoint (after identifying which buffers must be written).
  68       arg0 is the total number of buffers.
  69       arg1 is the number that are currently dirty and need to be written.</td></tr><tr><td><code class="literal">buffer-sync-written</code></td><td><code class="literal">(int)</code></td><td>Probe that fires after each buffer is written during checkpoint.
  70       arg0 is the ID number of the buffer.</td></tr><tr><td><code class="literal">buffer-sync-done</code></td><td><code class="literal">(int, int, int)</code></td><td>Probe that fires when all dirty buffers have been written.
  71       arg0 is the total number of buffers.
  72       arg1 is the number of buffers actually written by the checkpoint process.
  73       arg2 is the number that were expected to be written (arg1 of
  74       <code class="literal">buffer-sync-start</code>); any difference reflects other processes flushing
  75       buffers during the checkpoint.</td></tr><tr><td><code class="literal">buffer-checkpoint-sync-start</code></td><td><code class="literal">()</code></td><td>Probe that fires after dirty buffers have been written to the
  76       kernel, and before starting to issue fsync requests.</td></tr><tr><td><code class="literal">buffer-checkpoint-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when syncing of buffers to disk is
  77       complete.</td></tr><tr><td><code class="literal">twophase-checkpoint-start</code></td><td><code class="literal">()</code></td><td>Probe that fires when the two-phase portion of a checkpoint is
  78       started.</td></tr><tr><td><code class="literal">twophase-checkpoint-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when the two-phase portion of a checkpoint is
  79       complete.</td></tr><tr><td><code class="literal">buffer-extend-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int, unsigned int)</code></td><td>Probe that fires when a relation extension starts.
  80        arg0 contains the fork to be extended. arg1, arg2, and arg3 contain the
  81        tablespace, database, and relation OIDs identifying the relation.  arg4
  82        is the ID of the backend which created the temporary relation for a
  83        local buffer, or <code class="symbol">INVALID_PROC_NUMBER</code> (-1) for a shared
  84        buffer. arg5 is the number of blocks the caller would like to extend
  85        by.</td></tr><tr><td><code class="literal">buffer-extend-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int, unsigned int, BlockNumber)</code></td><td>Probe that fires when a relation extension is complete.
  86        arg0 contains the fork to be extended. arg1, arg2, and arg3 contain the
  87        tablespace, database, and relation OIDs identifying the relation.  arg4
  88        is the ID of the backend which created the temporary relation for a
  89        local buffer, or <code class="symbol">INVALID_PROC_NUMBER</code> (-1) for a shared
  90        buffer. arg5 is the number of blocks the relation was extended by, this
  91        can be less than the number in the
  92        <code class="literal">buffer-extend-start</code> due to resource
  93        constraints. arg6 contains the BlockNumber of the first new
  94        block.</td></tr><tr><td><code class="literal">buffer-read-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</code></td><td>Probe that fires when a buffer read is started.
  95       arg0 and arg1 contain the fork and block numbers of the page.
  96       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
  97       identifying the relation.
  98       arg5 is the ID of the backend which created the temporary relation for a
  99       local buffer, or <code class="symbol">INVALID_PROC_NUMBER</code> (-1) for a shared buffer.
 100       </td></tr><tr><td><code class="literal">buffer-read-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int, bool)</code></td><td>Probe that fires when a buffer read is complete.
 101       arg0 and arg1 contain the fork and block numbers of the page.
 102       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
 103       identifying the relation.
 104       arg5 is the ID of the backend which created the temporary relation for a
 105       local buffer, or <code class="symbol">INVALID_PROC_NUMBER</code> (-1) for a shared buffer.
 106       arg6 is true if the buffer was found in the pool, false if not.</td></tr><tr><td><code class="literal">buffer-flush-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid)</code></td><td>Probe that fires before issuing any write request for a shared
 107       buffer.
 108       arg0 and arg1 contain the fork and block numbers of the page.
 109       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
 110       identifying the relation.</td></tr><tr><td><code class="literal">buffer-flush-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid)</code></td><td>Probe that fires when a write request is complete.  (Note
 111       that this just reflects the time to pass the data to the kernel;
 112       it's typically not actually been written to disk yet.)
 113       The arguments are the same as for <code class="literal">buffer-flush-start</code>.</td></tr><tr><td><code class="literal">wal-buffer-write-dirty-start</code></td><td><code class="literal">()</code></td><td>Probe that fires when a server process begins to write a
 114       dirty WAL buffer because no more WAL buffer space is available.
 115       (If this happens often, it implies that
 116       <a class="xref" href="runtime-config-wal.html#GUC-WAL-BUFFERS">wal_buffers</a> is too small.)</td></tr><tr><td><code class="literal">wal-buffer-write-dirty-done</code></td><td><code class="literal">()</code></td><td>Probe that fires when a dirty WAL buffer write is complete.</td></tr><tr><td><code class="literal">wal-insert</code></td><td><code class="literal">(unsigned char, unsigned char)</code></td><td>Probe that fires when a WAL record is inserted.
 117       arg0 is the resource manager (rmid) for the record.
 118       arg1 contains the info flags.</td></tr><tr><td><code class="literal">wal-switch</code></td><td><code class="literal">()</code></td><td>Probe that fires when a WAL segment switch is requested.</td></tr><tr><td><code class="literal">smgr-md-read-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</code></td><td>Probe that fires when beginning to read a block from a relation.
 119       arg0 and arg1 contain the fork and block numbers of the page.
 120       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
 121       identifying the relation.
 122       arg5 is the ID of the backend which created the temporary relation for a
 123       local buffer, or <code class="symbol">INVALID_PROC_NUMBER</code> (-1) for a shared buffer.</td></tr><tr><td><code class="literal">smgr-md-read-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)</code></td><td>Probe that fires when a block read is complete.
 124       arg0 and arg1 contain the fork and block numbers of the page.
 125       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
 126       identifying the relation.
 127       arg5 is the ID of the backend which created the temporary relation for a
 128       local buffer, or <code class="symbol">INVALID_PROC_NUMBER</code> (-1) for a shared buffer.
 129       arg6 is the number of bytes actually read, while arg7 is the number
 130       requested (if these are different it indicates a short read).</td></tr><tr><td><code class="literal">smgr-md-write-start</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int)</code></td><td>Probe that fires when beginning to write a block to a relation.
 131       arg0 and arg1 contain the fork and block numbers of the page.
 132       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
 133       identifying the relation.
 134       arg5 is the ID of the backend which created the temporary relation for a
 135       local buffer, or <code class="symbol">INVALID_PROC_NUMBER</code> (-1) for a shared buffer.</td></tr><tr><td><code class="literal">smgr-md-write-done</code></td><td><code class="literal">(ForkNumber, BlockNumber, Oid, Oid, Oid, int, int, int)</code></td><td>Probe that fires when a block write is complete.
 136       arg0 and arg1 contain the fork and block numbers of the page.
 137       arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs
 138       identifying the relation.
 139       arg5 is the ID of the backend which created the temporary relation for a
 140       local buffer, or <code class="symbol">INVALID_PROC_NUMBER</code> (-1) for a shared buffer.
 141       arg6 is the number of bytes actually written, while arg7 is the number
 142       requested (if these are different it indicates a short write).</td></tr><tr><td><code class="literal">sort-start</code></td><td><code class="literal">(int, bool, int, int, bool, int)</code></td><td>Probe that fires when a sort operation is started.
 143       arg0 indicates heap, index or datum sort.
 144       arg1 is true for unique-value enforcement.
 145       arg2 is the number of key columns.
 146       arg3 is the number of kilobytes of work memory allowed.
 147       arg4 is true if random access to the sort result is required.
 148       arg5 indicates serial when <code class="literal">0</code>, parallel worker when
 149       <code class="literal">1</code>, or parallel leader when <code class="literal">2</code>.</td></tr><tr><td><code class="literal">sort-done</code></td><td><code class="literal">(bool, long)</code></td><td>Probe that fires when a sort is complete.
 150       arg0 is true for external sort, false for internal sort.
 151       arg1 is the number of disk blocks used for an external sort,
 152       or kilobytes of memory used for an internal sort.</td></tr><tr><td><code class="literal">lwlock-acquire</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when an LWLock has been acquired.
 153       arg0 is the LWLock's tranche.
 154       arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lwlock-release</code></td><td><code class="literal">(char *)</code></td><td>Probe that fires when an LWLock has been released (but note
 155       that any released waiters have not yet been awakened).
 156       arg0 is the LWLock's tranche.</td></tr><tr><td><code class="literal">lwlock-wait-start</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when an LWLock was not immediately available and
 157       a server process has begun to wait for the lock to become available.
 158       arg0 is the LWLock's tranche.
 159       arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lwlock-wait-done</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when a server process has been released from its
 160       wait for an LWLock (it does not actually have the lock yet).
 161       arg0 is the LWLock's tranche.
 162       arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lwlock-condacquire</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when an LWLock was successfully acquired when the
 163       caller specified no waiting.
 164       arg0 is the LWLock's tranche.
 165       arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lwlock-condacquire-fail</code></td><td><code class="literal">(char *, LWLockMode)</code></td><td>Probe that fires when an LWLock was not successfully acquired when
 166       the caller specified no waiting.
 167       arg0 is the LWLock's tranche.
 168       arg1 is the requested lock mode, either exclusive or shared.</td></tr><tr><td><code class="literal">lock-wait-start</code></td><td><code class="literal">(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)</code></td><td>Probe that fires when a request for a heavyweight lock (lmgr lock)
 169       has begun to wait because the lock is not available.
 170       arg0 through arg3 are the tag fields identifying the object being
 171       locked.  arg4 indicates the type of object being locked.
 172       arg5 indicates the lock type being requested.</td></tr><tr><td><code class="literal">lock-wait-done</code></td><td><code class="literal">(unsigned int, unsigned int, unsigned int, unsigned int, unsigned int, LOCKMODE)</code></td><td>Probe that fires when a request for a heavyweight lock (lmgr lock)
 173       has finished waiting (i.e., has acquired the lock).
 174       The arguments are the same as for <code class="literal">lock-wait-start</code>.</td></tr><tr><td><code class="literal">deadlock-found</code></td><td><code class="literal">()</code></td><td>Probe that fires when a deadlock is found by the deadlock
 175       detector.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="TYPEDEFS-TABLE"><p class="title"><strong>Table 27.50. Defined Types Used in Probe Parameters</strong></p><div class="table-contents"><table class="table" summary="Defined Types Used in Probe Parameters" border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Type</th><th>Definition</th></tr></thead><tbody><tr><td><code class="type">LocalTransactionId</code></td><td><code class="type">unsigned int</code></td></tr><tr><td><code class="type">LWLockMode</code></td><td><code class="type">int</code></td></tr><tr><td><code class="type">LOCKMODE</code></td><td><code class="type">int</code></td></tr><tr><td><code class="type">BlockNumber</code></td><td><code class="type">unsigned int</code></td></tr><tr><td><code class="type">Oid</code></td><td><code class="type">unsigned int</code></td></tr><tr><td><code class="type">ForkNumber</code></td><td><code class="type">int</code></td></tr><tr><td><code class="type">bool</code></td><td><code class="type">unsigned char</code></td></tr></tbody></table></div></div><br class="table-break" /></div><div class="sect2" id="USING-TRACE-POINTS"><div class="titlepage"><div><div><h3 class="title">27.5.3. Using Probes <a href="#USING-TRACE-POINTS" class="id_link">#</a></h3></div></div></div><p>
 176    The example below shows a DTrace script for analyzing transaction
 177    counts in the system, as an alternative to snapshotting
 178    <code class="structname">pg_stat_database</code> before and after a performance test:
 179 </p><pre class="programlisting">
 180 #!/usr/sbin/dtrace -qs
 181
 182 postgresql$1:::transaction-start
 183 {
 184       @start["Start"] = count();
 185       self-&gt;ts  = timestamp;
 186 }
 187
 188 postgresql$1:::transaction-abort
 189 {
 190       @abort["Abort"] = count();
 191 }
 192
 193 postgresql$1:::transaction-commit
 194 /self-&gt;ts/
 195 {
 196       @commit["Commit"] = count();
 197       @time["Total time (ns)"] = sum(timestamp - self-&gt;ts);
 198       self-&gt;ts=0;
 199 }
 200 </pre><p>
 201    When executed, the example D script gives output such as:
 202 </p><pre class="screen">
 203 # ./txn_count.d `pgrep -n postgres` or ./txn_count.d &lt;PID&gt;
 204 ^C
 205
 206 Start                                          71
 207 Commit                                         70
 208 Total time (ns)                        2312105013
 209 </pre><p>
 210   </p><div class="note"><h3 class="title">Note</h3><p>
 211     SystemTap uses a different notation for trace scripts than DTrace does,
 212     even though the underlying trace points are compatible.  One point worth
 213     noting is that at this writing, SystemTap scripts must reference probe
 214     names using double underscores in place of hyphens.  This is expected to
 215     be fixed in future SystemTap releases.
 216    </p></div><p>
 217    You should remember that DTrace scripts need to be carefully written and
 218    debugged, otherwise the trace information collected might
 219    be meaningless. In most cases where problems are found it is the
 220    instrumentation that is at fault, not the underlying system. When
 221    discussing information found using dynamic tracing, be sure to enclose
 222    the script used to allow that too to be checked and discussed.
 223   </p></div><div class="sect2" id="DEFINING-TRACE-POINTS"><div class="titlepage"><div><div><h3 class="title">27.5.4. Defining New Probes <a href="#DEFINING-TRACE-POINTS" class="id_link">#</a></h3></div></div></div><p>
 224    New probes can be defined within the code wherever the developer
 225    desires, though this will require a recompilation. Below are the steps
 226    for inserting new probes:
 227   </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
 228      Decide on probe names and data to be made available through the probes
 229     </p></li><li class="step"><p>
 230      Add the probe definitions to <code class="filename">src/backend/utils/probes.d</code>
 231     </p></li><li class="step"><p>
 232      Include <code class="filename">pg_trace.h</code> if it is not already present in the
 233      module(s) containing the probe points, and insert
 234      <code class="literal">TRACE_POSTGRESQL</code> probe macros at the desired locations
 235      in the source code
 236     </p></li><li class="step"><p>
 237      Recompile and verify that the new probes are available
 238     </p></li></ol></div><p><strong>Example: </strong>
 239     Here is an example of how you would add a probe to trace all new
 240     transactions by transaction ID.
 241    </p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>
 242      Decide that the probe will be named <code class="literal">transaction-start</code> and
 243      requires a parameter of type <code class="type">LocalTransactionId</code>
 244     </p></li><li class="step"><p>
 245      Add the probe definition to <code class="filename">src/backend/utils/probes.d</code>:
 246 </p><pre class="programlisting">
 247 probe transaction__start(LocalTransactionId);
 248 </pre><p>
 249      Note the use of the double underline in the probe name. In a DTrace
 250      script using the probe, the double underline needs to be replaced with a
 251      hyphen, so <code class="literal">transaction-start</code> is the name to document for
 252      users.
 253     </p></li><li class="step"><p>
 254      At compile time, <code class="literal">transaction__start</code> is converted to a macro
 255      called <code class="literal">TRACE_POSTGRESQL_TRANSACTION_START</code> (notice the
 256      underscores are single here), which is available by including
 257      <code class="filename">pg_trace.h</code>.  Add the macro call to the appropriate location
 258      in the source code.  In this case, it looks like the following:
 259
 260 </p><pre class="programlisting">
 261 TRACE_POSTGRESQL_TRANSACTION_START(vxid.localTransactionId);
 262 </pre><p>
 263     </p></li><li class="step"><p>
 264      After recompiling and running the new binary, check that your newly added
 265      probe is available by executing the following DTrace command.  You
 266      should see similar output:
 267 </p><pre class="screen">
 268 # dtrace -ln transaction-start
 269    ID    PROVIDER          MODULE           FUNCTION NAME
 270 18705 postgresql49878     postgres     StartTransactionCommand transaction-start
 271 18755 postgresql49877     postgres     StartTransactionCommand transaction-start
 272 18805 postgresql49876     postgres     StartTransactionCommand transaction-start
 273 18855 postgresql49875     postgres     StartTransactionCommand transaction-start
 274 18986 postgresql49873     postgres     StartTransactionCommand transaction-start
 275 </pre><p>
 276     </p></li></ol></div><p>
 277    There are a few things to be careful about when adding trace macros
 278    to the C code:
 279
 280    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
 281       You should take care that the data types specified for a probe's
 282       parameters match the data types of the variables used in the macro.
 283       Otherwise, you will get compilation errors.
 284      </p></li><li class="listitem"><p>
 285       On most platforms, if <span class="productname">PostgreSQL</span> is
 286       built with <code class="option">--enable-dtrace</code>, the arguments to a trace
 287       macro will be evaluated whenever control passes through the
 288       macro, <span class="emphasis"><em>even if no tracing is being done</em></span>.  This is
 289       usually not worth worrying about if you are just reporting the
 290       values of a few local variables.  But beware of putting expensive
 291       function calls into the arguments.  If you need to do that,
 292       consider protecting the macro with a check to see if the trace
 293       is actually enabled:
 294
 295 </p><pre class="programlisting">
 296 if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED())
 297     TRACE_POSTGRESQL_TRANSACTION_START(some_function(...));
 298 </pre><p>
 299
 300       Each trace macro has a corresponding <code class="literal">ENABLED</code> macro.
 301      </p></li></ul></div><p>
 302
 303   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="progress-reporting.html" title="27.4. Progress Reporting">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="monitoring.html" title="Chapter 27. Monitoring Database Activity">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="diskusage.html" title="27.6. Monitoring Disk Usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">27.4. Progress Reporting </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 27.6. Monitoring Disk Usage</td></tr></table></div></body></html>