Add documentation of the fact that dtrace probes evaluate their parameters

even when not active.  Explain how to prevent that with an ENABLED() check.

diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml
index d257d09ade8e717bfb2ef7358e9ca41d4acf4eaf..e93560baec9d97f49f2ab84ffc703f7cebf02b40 100644 (file)
--- a/doc/src/sgml/monitoring.sgml
+++ b/doc/src/sgml/monitoring.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Monitoring Database Activity
@@ -1051,7 +1051,8 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
   
    A number of standard probes are provided in the source code,
    as shown in .
-   More can certainly be added to enhance PostgreSQL's observability.
+   More can certainly be added to enhance PostgreSQL's
+   observability.
   
 
  
@@ -1605,8 +1606,9 @@ Total time (ns)                        2312105013
    
     
      Include 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
+     TRACE_POSTGRESQL probe macros at the desired locations
+     in the source code
     
    
 
@@ -1628,8 +1630,8 @@ Total time (ns)                        2312105013
   
    
     
-     Decide that the probe will be named transaction-start and requires
-     a parameter of type LocalTransactionId
+     Decide that the probe will be named transaction-start and
+     requires a parameter of type LocalTransactionId
     
    
 
@@ -1637,29 +1639,22 @@ Total time (ns)                        2312105013
     
      Add the probe definition to src/backend/utils/probes.d:
 
-      ...
       probe transaction__start(LocalTransactionId);
-      ...
 
      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.
-    
-
-    
-     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 transaction-start is the name to document for
+     users.
     
    
 
    
     
-     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 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, transaction__start is converted to a macro
+     called TRACE_POSTGRESQL_TRANSACTION_START (notice the
+     underscores are single here), which is available by including
+     pg_trace.h.  Add the macro call to the appropriate location
+     in the source code.  In this case, it looks like the following:
 
 
     TRACE_POSTGRESQL_TRANSACTION_START(vxid.localTransactionId);
@@ -1685,6 +1680,44 @@ Total time (ns)                        2312105013
    
   
 
+  
+   There are a few things to be careful about when adding trace macros
+   to the C code:
+
+   
+    
+     
+      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.
+     
+    
+
+
+    
+     
+      On most platforms, if PostgreSQL is
+      built with --enable-dtrace, the arguments to a trace
+      macro will be evaluated whenever control passes through the
+      macro, 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:
+
+
+    if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED())
+        TRACE_POSTGRESQL_TRANSACTION_START(some_function(...));
+
+
+      Each trace macro has a corresponding ENABLED macro.
+     
+    
+   
+
+  
+