From 2938f8c4ea09e727d12ecaf32de36fcbcb5fd815 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 28 Mar 2009 00:10:23 +0000
Subject: [PATCH] Add documentation of the fact that dtrace probes evaluate
their parameters even when not active. Explain how to prevent that with an
ENABLED() check.
---
doc/src/sgml/monitoring.sgml | 73 ++++++++++++++++++++++++++----------
1 file changed, 53 insertions(+), 20 deletions(-)
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index d257d09ade8..e93560baec9 100644
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.65 2009/03/23 01:52:38 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.66 2009/03/28 00:10:23 tgl Exp $ -->
<chapter id="monitoring">
<title>Monitoring Database Activity</title>
@@ -1051,7 +1051,8 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
<para>
A number of standard probes are provided in the source code,
as shown in <xref linkend="dtrace-probe-point-table">.
- More can certainly be added to enhance PostgreSQL's observability.
+ More can certainly be added to enhance <productname>PostgreSQL</>'s
+ observability.
</para>
<table id="dtrace-probe-point-table">
@@ -1605,8 +1606,9 @@ Total time (ns) 2312105013
<step>
<para>
Include <filename>pg_trace.h</> if it is not already present in the
- module(s) containing the probe points, and insert TRACE_POSTGRESQL
- probe macros at the desired locations in the source code
+ module(s) containing the probe points, and insert
+ <literal>TRACE_POSTGRESQL</> probe macros at the desired locations
+ in the source code
</para>
</step>
@@ -1628,8 +1630,8 @@ Total time (ns) 2312105013
<procedure>
<step>
<para>
- Decide that the probe will be named transaction-start and requires
- a parameter of type LocalTransactionId
+ Decide that the probe will be named <literal>transaction-start</> and
+ requires a parameter of type LocalTransactionId
</para>
</step>
@@ -1637,29 +1639,22 @@ Total time (ns) 2312105013
<para>
Add the probe definition to <filename>src/backend/utils/probes.d</>:
<programlisting>
- ...
probe transaction__start(LocalTransactionId);
- ...
</programlisting>
Note the use of the double underline in the probe name. In a DTrace
script using the probe, the double underline needs to be replaced with a
- hyphen.
- </para>
-
- <para>
- You should take care that the data types specified for the probe
- parameters match the data types of the variables used in the macro.
- Otherwise, you will get compilation errors.
+ hyphen, so <literal>transaction-start</> is the name to document for
+ users.
</para>
</step>
<step>
<para>
- At compile time, transaction__start is converted to a macro called
- TRACE_POSTGRESQL_TRANSACTION_START (note the underscores are single
- here), which is available by including <filename>pg_trace.h</>.
- Add the macro call to the appropriate location in the source code.
- In this case, it looks like the following:
+ At compile time, <literal>transaction__start</> is converted to a macro
+ called <literal>TRACE_POSTGRESQL_TRANSACTION_START</> (notice the
+ underscores are single here), which is available by including
+ <filename>pg_trace.h</>. Add the macro call to the appropriate location
+ in the source code. In this case, it looks like the following:
<programlisting>
TRACE_POSTGRESQL_TRANSACTION_START(vxid.localTransactionId);
@@ -1685,6 +1680,44 @@ Total time (ns) 2312105013
</step>
</procedure>
+ <para>
+ There are a few things to be careful about when adding trace macros
+ to the C code:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ You should take care that the data types specified for a probe's
+ parameters match the data types of the variables used in the macro.
+ Otherwise, you will get compilation errors.
+ </para>
+ </listitem>
+
+
+ <listitem>
+ <para>
+ On most platforms, if <productname>PostgreSQL</productname> is
+ built with <option>--enable-dtrace</>, the arguments to a trace
+ macro will be evaluated whenever control passes through the
+ macro, <emphasis>even if no tracing is being done</>. This is
+ usually not worth worrying about if you are just reporting the
+ values of a few local variables. But beware of putting expensive
+ function calls into the arguments. If you need to do that,
+ consider protecting the macro with a check to see if the trace
+ is actually enabled:
+
+<programlisting>
+ if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED())
+ TRACE_POSTGRESQL_TRANSACTION_START(some_function(...));
+</programlisting>
+
+ Each trace macro has a corresponding <literal>ENABLED</> macro.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+
</sect2>
</sect1>
--
GitLab