Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes15kdownloads
dynamic-trace.html303 linesDownload Raw Back to 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>28.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="28.4. Progress Reporting" /><link rel="next" href="diskusage.html" title="Chapter 29. 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">28.5. Dynamic Tracing</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="progress-reporting.html" title="28.4. Progress Reporting">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><th width="60%" align="center">Chapter 28. Monitoring Database Activity</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="diskusage.html" title="Chapter 29. 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">28.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">28.5.1. Compiling for Dynamic Tracing</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#TRACE-POINTS">28.5.2. Built-in Probes</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#USING-TRACE-POINTS">28.5.3. Using Probes</a></span></dt><dt><span class="sect2"><a href="dynamic-trace.html#DEFINING-TRACE-POINTS">28.5.4. Defining New Probes</a></span></dt></dl></div><a id="id-1.6.15.10.2" class="indexterm"></a><p>3   <span class="productname">PostgreSQL</span> provides facilities to support4   dynamic tracing of the database server. This allows an external5   utility to be called at specific points in the code and thereby trace6   execution.7  </p><p>8   A number of probes or trace points are already inserted into the source9   code. These probes are intended to be used by database developers and10   administrators. By default the probes are not compiled into11   <span class="productname">PostgreSQL</span>; the user needs to explicitly tell12   the configure script to make the probes available.13  </p><p>14   Currently, the15   <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 available17   on Solaris, macOS, FreeBSD, NetBSD, and Oracle Linux.  The18   <a class="ulink" href="https://sourceware.org/systemtap/" target="_top">SystemTap</a> project19   for Linux provides a DTrace equivalent and can also be used.  Supporting other dynamic20   tracing utilities is theoretically possible by changing the definitions for21   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">28.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 to24   explicitly tell the configure script to make the probes available25   in <span class="productname">PostgreSQL</span>. To include DTrace support26   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">28.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 28.48. Built-in DTrace Probes">Table 28.48</a>;30   <a class="xref" href="dynamic-trace.html#TYPEDEFS-TABLE" title="Table 28.49. Defined Types Used in Probe Parameters">Table 28.49</a>31   shows the types used in the probes.  More probes can certainly be32   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 28.48. 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 its43      <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 checkpoint46      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 of49      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 shutdown52      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 is53      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 is54      started.55      arg0 is true for normal checkpoint, false for shutdown56      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 is57      complete. arg0 has the same meaning as for58      <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 is59      started.60      arg0 is true for normal checkpoint, false for shutdown61      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 is62      complete. arg0 has the same meaning as for63      <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 checkpoint64      is started.65      arg0 holds the bitwise flags used to distinguish different checkpoint66      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 during67      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 of74      <code class="literal">buffer-sync-start</code>); any difference reflects other processes flushing75      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 the76      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 is77      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 is78      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 is79      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 the81       tablespace, database, and relation OIDs identifying the relation.  arg482       is the ID of the backend which created the temporary relation for a83       local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared84       buffer. arg5 is the number of blocks the caller would like to extend85       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 the87       tablespace, database, and relation OIDs identifying the relation.  arg488       is the ID of the backend which created the temporary relation for a89       local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared90       buffer. arg5 is the number of blocks the relation was extended by, this91       can be less than the number in the92       <code class="literal">buffer-extend-start</code> due to resource93       constraints. arg6 contains the BlockNumber of the first new94       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 OIDs97      identifying the relation.98      arg5 is the ID of the backend which created the temporary relation for a99      local buffer, or <code class="symbol">InvalidBackendId</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 OIDs103      identifying the relation.104      arg5 is the ID of the backend which created the temporary relation for a105      local buffer, or <code class="symbol">InvalidBackendId</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 shared107      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 OIDs110      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.  (Note111      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 a114      dirty WAL buffer because no more WAL buffer space is available.115      (If this happens often, it implies that116      <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 OIDs121      identifying the relation.122      arg5 is the ID of the backend which created the temporary relation for a123      local buffer, or <code class="symbol">InvalidBackendId</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 OIDs126      identifying the relation.127      arg5 is the ID of the backend which created the temporary relation for a128      local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared buffer.129      arg6 is the number of bytes actually read, while arg7 is the number130      requested (if these are different it indicates trouble).</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 OIDs133      identifying the relation.134      arg5 is the ID of the backend which created the temporary relation for a135      local buffer, or <code class="symbol">InvalidBackendId</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 OIDs138      identifying the relation.139      arg5 is the ID of the backend which created the temporary relation for a140      local buffer, or <code class="symbol">InvalidBackendId</code> (-1) for a shared buffer.141      arg6 is the number of bytes actually written, while arg7 is the number142      requested (if these are different it indicates trouble).</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 when149      <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 note155      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 and157      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 its160      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 the163      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 when166      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 being171      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 deadlock175      detector.</td></tr></tbody></table></div></div><br class="table-break" /><div class="table" id="TYPEDEFS-TABLE"><p class="title"><strong>Table 28.49. 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">28.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 transaction177   counts in the system, as an alternative to snapshotting178   <code class="structname">pg_stat_database</code> before and after a performance test:179</p><pre class="programlisting">180#!/usr/sbin/dtrace -qs181 182postgresql$1:::transaction-start183{184      @start["Start"] = count();185      self-&gt;ts  = timestamp;186}187 188postgresql$1:::transaction-abort189{190      @abort["Abort"] = count();191}192 193postgresql$1:::transaction-commit194/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^C205 206Start                                          71207Commit                                         70208Total time (ns)                        2312105013209</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 worth213    noting is that at this writing, SystemTap scripts must reference probe214    names using double underscores in place of hyphens.  This is expected to215    be fixed in future SystemTap releases.216   </p></div><p>217   You should remember that DTrace scripts need to be carefully written and218   debugged, otherwise the trace information collected might219   be meaningless. In most cases where problems are found it is the220   instrumentation that is at fault, not the underlying system. When221   discussing information found using dynamic tracing, be sure to enclose222   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">28.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 developer225   desires, though this will require a recompilation. Below are the steps226   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 probes229    </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 the233     module(s) containing the probe points, and insert234     <code class="literal">TRACE_POSTGRESQL</code> probe macros at the desired locations235     in the source code236    </p></li><li class="step"><p>237     Recompile and verify that the new probes are available238    </p></li></ol></div><p><strong>Example: </strong>239    Here is an example of how you would add a probe to trace all new240    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> and243     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">247probe transaction__start(LocalTransactionId);248</pre><p>249     Note the use of the double underline in the probe name. In a DTrace250     script using the probe, the double underline needs to be replaced with a251     hyphen, so <code class="literal">transaction-start</code> is the name to document for252     users.253    </p></li><li class="step"><p>254     At compile time, <code class="literal">transaction__start</code> is converted to a macro255     called <code class="literal">TRACE_POSTGRESQL_TRANSACTION_START</code> (notice the256     underscores are single here), which is available by including257     <code class="filename">pg_trace.h</code>.  Add the macro call to the appropriate location258     in the source code.  In this case, it looks like the following:259 260</p><pre class="programlisting">261TRACE_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 added265     probe is available by executing the following DTrace command.  You266     should see similar output:267</p><pre class="screen">268# dtrace -ln transaction-start269   ID    PROVIDER          MODULE           FUNCTION NAME27018705 postgresql49878     postgres     StartTransactionCommand transaction-start27118755 postgresql49877     postgres     StartTransactionCommand transaction-start27218805 postgresql49876     postgres     StartTransactionCommand transaction-start27318855 postgresql49875     postgres     StartTransactionCommand transaction-start27418986 postgresql49873     postgres     StartTransactionCommand transaction-start275</pre><p>276    </p></li></ol></div><p>277   There are a few things to be careful about when adding trace macros278   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's282      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> is286      built with <code class="option">--enable-dtrace</code>, the arguments to a trace287      macro will be evaluated whenever control passes through the288      macro, <span class="emphasis"><em>even if no tracing is being done</em></span>.  This is289      usually not worth worrying about if you are just reporting the290      values of a few local variables.  But beware of putting expensive291      function calls into the arguments.  If you need to do that,292      consider protecting the macro with a check to see if the trace293      is actually enabled:294 295</p><pre class="programlisting">296if (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="28.4. Progress Reporting">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="monitoring.html" title="Chapter 28. Monitoring Database Activity">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="diskusage.html" title="Chapter 29. Monitoring Disk Usage">Next</a></td></tr><tr><td width="40%" align="left" valign="top">28.4. Progress Reporting </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 29. Monitoring Disk Usage</td></tr></table></div></body></html>
codekingpro/portable-devtools · Team Ai