- publishing free software manuals
The PostgreSQL 9.0 Reference Manual - Volume 3 - Server Administration Guide
by The PostgreSQL Global Development Group
Paperback (6"x9"), 274 pages
ISBN 9781906966072
RRP £9.95 ($14.95)

Sales of this book support the PostgreSQL project! Get a printed copy>>>

13.4.4 Defining New Probes

New probes can be defined within the code wherever the developer desires, though this will require a recompilation. Below are the steps for inserting new probes:

  1. Decide on probe names and data to be made available through the probes
  2. Add the probe definitions to ‘src/backend/utils/probes.d’
  3. 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
  4. Recompile and verify that the new probes are available

Example:. Here is an example of how you would add a probe to trace all new transactions by transaction ID.

  1. Decide that the probe will be named transaction-start and requires a parameter of type LocalTransactionId
  2. 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, so transaction-start is the name to document for users.
  3. 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);
    
  4. After recompiling and running the new binary, check that your newly added probe is available by executing the following DTrace command. You should see similar output:
    # dtrace -ln transaction-start
       ID    PROVIDER          MODULE           FUNCTION NAME
    18705 postgresql49878     postgres    
       StartTransactionCommand transaction-start
    18755 postgresql49877     postgres    
       StartTransactionCommand transaction-start
    18805 postgresql49876     postgres    
       StartTransactionCommand transaction-start
    18855 postgresql49875     postgres    
       StartTransactionCommand transaction-start
    18986 postgresql49873     postgres    
       StartTransactionCommand transaction-start
    

There are a few things to be careful about when adding trace macros to the C code:

ISBN 9781906966072The PostgreSQL 9.0 Reference Manual - Volume 3 - Server Administration GuideSee the print edition