codekingpro/portable-devtools
115k
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->ts = timestamp;186}187 188postgresql$1:::transaction-abort189{190 @abort["Abort"] = count();191}192 193postgresql$1:::transaction-commit194/self->ts/195{196 @commit["Commit"] = count();197 @time["Total time (ns)"] = sum(timestamp - self->ts);198 self->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 <PID>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>