Index: doc/src/sgml/monitoring.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/monitoring.sgml,v
retrieving revision 1.63
diff -u -3 -p -r1.63 monitoring.sgml
--- doc/src/sgml/monitoring.sgml 11 Nov 2008 20:06:21 -0000 1.63
+++ doc/src/sgml/monitoring.sgml 26 Feb 2009 22:18:31 -0000
@@ -1009,23 +1009,25 @@ SELECT pg_stat_get_backend_pid(s.backend
PostgreSQL provides facilities to support
dynamic tracing of the database server. This allows an external
utility to be called at specific points in the code and thereby trace
- execution. Currently, this facility is primarily intended for use by
- database developers, as it requires substantial familiarity with the code.
+ execution.
- A number of probes or trace points are already inserted
- into the source code. By default these probes are not compiled into the
+ A number of probes or trace points are already inserted into the source
+ code. These probes are intended to be used by database developers and
+ administrators. By default the probes are not compiled into the
binary, and the user needs to explicitly tell the configure script to make
the probes available in PostgreSQL.
- Currently, only the DTrace utility is supported, which is available
- on Solaris Express, Solaris 10, and Mac OS X Leopard. It is expected that
- DTrace will be available in the future on FreeBSD.
- Supporting other dynamic tracing utilities is theoretically possible by
- changing the definitions for the macros in
+ Currently, only the
+ DTrace
+ utility is supported, which is available
+ on OpenSolaris, Solaris 10, and Mac OS X Leopard. It is expected that
+ DTrace will be available in the future on FreeBSD and possibly other
+ operating systems. Supporting other dynamic tracing utilities is
+ theoretically possible by changing the definitions for the macros in
src/include/utils/probes.h.
@@ -1045,93 +1047,387 @@ SELECT pg_stat_get_backend_pid(s.backend
Built-in Probes
- A few standard probes are provided in the source code
- (of course, more can be added as needed for a particular problem).
- These are shown in .
+ A number of standard probes are provided in the source code, and more
+ can certainly be added to enhance PostgreSQL's observability. There are two categories
+ of probes, those that are targeted toward database administrators and those for developers.
+ They are shown in and
+ .
-
- Built-in Probes
+
+ Built-in Probes for Administrators
Name
Parameters
- Overview
+ Description
+
transaction-start
- (int transactionId)
- The start of a new transaction.
+ (LocalTransactionId)
+ Probe that fires at the start of a new transaction. arg0 is the transaction id.
transaction-commit
- (int transactionId)
- The successful completion of a transaction.
+ (LocalTransactionId)
+ Probe that fires when a transaction completes successfully. arg0 is the transaction id.
transaction-abort
- (int transactionId)
- The unsuccessful completion of a transaction.
+ (LocalTransactionId)
+ Probes that fires when a transaction does not complete successfully. arg0 is the transaction id.
+
+
+ query-start
+ (const char *)
+ Probe that fires when the execution of a statement is started. arg0 is the query string.
+
+
+ query-done
+ (const char *)
+ Probe that fires when the execution of a statement is complete. arg0 is the query string.
+
+
+ query-parse-start
+ (const char *)
+ Probe that fires when the parsing of a query is started. arg0 is the query string.
+
+
+ query-parse-done
+ (const char *)
+ Probe that fires when the parsing of a query is complete. arg0 is the query string.
+
+
+ query-rewrite-start
+ (const char *)
+ Probe that fires when the rewriting of a query is started. arg0 is the query string.
+
+
+ query-rewrite-done
+ (const char *)
+ Probe that fires when the rewriting of a query is complete. arg0 is the query string.
+
+
+ query-plan-start
+ ()
+ Probe that fires when the planning of a query is started.
+
+
+ query-plan-done
+ ()
+ Probe that fires when the planning of a query is complete.
+
+
+ query-execute-start
+ ()
+ Probe that fires when the execution of a query is started.
+
+
+ query-execute-done
+ ()
+ Probe that fires when the execution of a query is complete.
+
+
+ statement-status
+ (const char *)
+ Probe that fires anytime an SQL statement is executed on the server. arg0 is the query string.
+
+
+ checkpoint-start
+ (int)
+ Probe that fires when a checkpoint is performed. arg0 holds the bitwise flags used to distinguish different checkpoints such as shutdown, immediate or force.
+
+
+ checkpoint-done
+ (int, int, int, int, int)
+ Probe that fires when a checkpoint is complete. arg0 is the number of buffers written. arg1 is the total number of buffers. arg2, arg3 and arg4 contain the number of xlog file(s) added, removed and recycled respectively.
+
+
+ clog-checkpoint-start
+ (bool)
+ Probe that fires when the CLOG portion of the checkpoint is started. arg0 is either true or false, true for normal checkpoint, false for postmaster shutdown.
+
+
+ clog-checkpoint-done
+ (bool)
+ Probe that fires when the CLOG portion of the checkpoint is complete. arg0 has the same meaning as clog-checkpoint-start.
+
+
+ subtrans-checkpoint-start
+ (bool)
+ Probe that fires when the SUBTRANS portion of the checkpoint is started. arg0 is either true or false, true for normal checkpoint, false for postmaster shutdown.
+
+
+ subtrans-checkpoint-done
+ (bool)
+ Probe that fires when the SUBTRANS portion of the checkpoint is complete. arg0 has the same meaning as subtrans-checkpoint-done.
+
+
+ multixact-checkpoint-start
+ (bool)
+ Probe that fires when the MultiXact portion of the checkpoint is started. arg0 is either true or false, true for normal checkpoint, false for postmaster shutdown.
+
+
+ multixact-checkpoint-done
+ (bool)
+ Probe that fires when the MultiXact portion of the checkpoint is complete. arg0 has the same meaning as multixact-checkpoint-start.
+
+
+ buffer-checkpoint-start
+ (int)
+ Probe that fires when the shared buffers portion of the checkpoint is started to flush out the buffers, and it's always followed by buffer-sync-start. arg0 holds the bitwise flags used to distinguish different checkpoints such as shutdown, immediate or force
+
+
+ buffer-checkpoint-sync-start
+ ()
+ Probe that fires to fsync buffers to disk, and it's always preceeded by buffer-checkpoint-start, buffer-sync-start, and buffer-flush-start. The time difference between buffer-checkpoint-start and buffer-checkpoint-sync-start is the write time, and the difference between buffer-checkpoint-sync-start and buffer-checkpoint-done is the sync time.
+
+
+ buffer-checkpoint-done
+ ()
+ Probe that fires when the shared buffers portion of the checkpoint is complete. This probe is fired after buffer-checkpoint-sync-start.
+
+
+ twophase-checkpoint-start
+ ()
+ Probe that fires when the two-phase portion of the checkpoint is started.
+
+
+ twophase-checkpoint-done
+ ()
+ Probe that fires when the two-phase portion of the checkpoint is complete.
+
+
+ buffer-hit
+ (bool)
+ Probe that fires when a read request is satisfied from the buffer cache. arg0 is either true or false, true for local buffer, false for shared buffer.
+
+
+ buffer-miss
+ (bool)
+ Probe that fires when a read request requires disk access. arg0 is either true or false, true for local buffer, false for shared buffer .
+
+
+ buffer-read-start
+ (ForkNumber, BlockNumber, Oid, Oid, Oid, bool)
+ Probe that fires when a buffer read is started. arg0 and arg1 contain the fork and block numbers. arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs respectively. arg5 is either true or false, true for local buffer, false for shared buffer.
+
+
+ buffer-read-done
+ (ForkNumber, BlockNumber, Oid, Oid, Oid, bool, bool)
+ Probe that fires when a buffer read is complete. arg0 and arg1 contain the fork and block numbers. arg2, arg3, and arg4 contain the tablespace, database, and relation OIDs respectively. arg5 is either true or false, true for local buffer, false for shared buffer. arg6 is true if buffer is found in the pool, false otherwise.
+
+
+ buffer-sync-start
+ (int, int)
+ Probe that fires to write out all dirty buffers in the pool at checkpoint time, and it's always preceeded by buffer-checkpoint-start and followed by buffer-flush-start. arg0 is the total number of buffers. arg1 is the number it intends to write.
+
+
+ buffer-sync-done
+ (int, int, int)
+ Probe that fires when all dirty buffers have been written. arg0 is the total number of buffers. arg1 is the number actually written. arg2 is the total number to write.
+
+
+ buffer-sync-written
+ (int)
+ Probe that fires when the buffer pool syncing is in progress (e.g. buffer-sync-start has fired) and a buffer has been successfully written.
+
+ buffer-flush-start
+ (Oid, Oid, Oid)
+ Probe that fires when a shared buffer needs to be physically written out to disk, and it's always preceeded by buffer-sync-start. This actually just passes the buffer contents to the kernel; the real write to disk happens later by the kernel. This is okay since the changes have already been written to the WAL. arg0, arg1, and arg2 contain the tablespace, database, and relation OIDs respectively.
+
+
+ buffer-flush-done
+ (Oid, Oid, Oid)
+ Probe that fires when the buffer flush is complete, and it's always followed by buffer-checkpoint-sync-start. arg0, arg1, and arg2 have the same meaning as buffer-flush-start.
+
+
+ buffer-write-dirty-start
+ (ForkNumber, BlockNumber, Oid, Oid, Oid)
+ Probe that fires when the server starts writting out dirty buffers, indicating that the bgwriter is ineffective or shared_buffers is too small. arg0 refers to a fork in a relation. arg1 is the disk block number. arg2, arg3, arg4 contain the tablespace, database, and relation OIDs respectively.
+
+
+ buffer-write-dirty-done
+ (ForkNumber, BlockNumber, Oid, Oid, Oid)
+ Probe that fires when the buffer write is complete. The arguments are the same as buffer-write-dirty-start probe.
+
+
+ wal-buffer-write-dirty-start
+ ()
+ Probe that fires when the server starts writting out dirty WAL buffers, indicating that no more WAL buffer pages are available. Increasing wal_buffers will reduce the writes and may improve performance.
+
+
+ wal-buffer-write-dirty-done
+ ()
+ Probe that fires when the WAL buffer write is complete.
+
+
+ xlog-insert
+ (unsigned char, unsigned char)
+ Probe that fires when data is inserted in the XLog. arg0 is the resource manager (rmid) for the record. arg1 represents the info flags.
+
+
+ xlog-switch
+ ()
+ Probe that fires when an XLog switch is requested. This is always immediately preceeded by an firing of the xlog-insert probe.
+
+
+ sort-start
+ (int, bool, int, int, bool)
+ Probe that fires when sort is performed. arg0 indicates heap, index or datum sort. arg1 is true for unique enforcement. arg2 is the number of keys. arg3 represents workMem. arg3 is true for random access.
+
+
+ sort-done
+ (unsigned long, long)
+ Probe that fires when sort is complete. arg0 is either true or false, true for external sort, false for internal sort. arg1 is the number of disk blocks used for external sort or memory used in KB for internal sort.
+
+
+ smgr-md-read-start
+ (ForkNumber, BlockNumber, Oid, Oid, Oid)
+ Probes that fires when reading a block from a relation. arg0 and arg1 contain fork and block number. arg2, arg3 and arg4 contain the tablespace, database and relation OIDs.
+
+
+ smgr-md-read-done
+ (ForkNumber, BlockNumber, Oid, Oid, Oid, const char *, int, int)
+ Probes that fires when a block read is complete. arg0 and arg1 contan fork and block number. arg2, arg3, arg4 contain the tablespace, database, and relation OIDs. arg5 is the path to the relation's file. arg6 is the number of bytes read. arg7 is the block size.
+
+
+ smgr-md-write-start
+ (ForkNumber, BlockNumber, Oid, Oid, Oid)
+ Probes that fires when writing a block to the appropriate relation. arg0 and arg1 contain fork and block number. arg2, arg3 and arg4 contain the tablespace, database and relation OIDs.
+
+
+ smgr-md-write-done
+ (ForkNumber, BlockNumber, Oid, Oid, Oid, const char *, int, int)
+ Probes that fires when a block write is complete. arg0 and arg1 contan fork and block number. arg2, arg3, arg4 contain the tablespace, database, and relation OIDs. arg5 is the path to the relation's file. arg6 is number of bytes read. arg7 is the block size.
+
+
+ deadlock-found
+ ()
+ Probe that fires when a deadlock is found by the deadlock detector.
+
+
+
+
+
+
+
+
+
+ Built-in Probes for Developers
+
+
+
+ Name
+ Parameters
+ Description
+
+
+
+
lwlock-acquire
- (int lockid, int mode)
- An LWLock has been acquired.
+ (LWLockId, LWLockMode)
+ Probe that fires when an LWLock has been acquired. arg0 is a predefined or dynamic ID defined in LWLockId enum. arg1 is a lock mode, either exclusive or shared.
lwlock-release
- (int lockid, int mode)
- An LWLock has been released.
+ (LWLockId)
+ Probe that fires when an LWLock has been released. arg0 is a predefined or dynamic ID defined in LWLockId enum.
- lwlock-startwait
- (int lockid, int mode)
- An LWLock was not immediately available and a backend
- has begun to wait for the lock to become available.
-
+ lwlock-wait-start
+ (LWLockId, LWLockMode)
+ Probe that fires when an LWLock was not immediately available and a backend has begun to wait for the lock to become available. arg0 is a predefined or dynamic ID defined in LWLockId enum. arg1 is a lock mode, either exclusive or shared .
- lwlock-endwait
- (int lockid, int mode)
- A backend has been released from its wait for an LWLock.
-
+ lwlock-wait-done
+ (LWLockId, LWLockMode)
+ Probe that fires when a backend has been released from its wait for an LWLock. arg0 is a predefined or dynamic ID defined in LWLockId enum. arg1 is a lock mode, either exclusive or shared.
lwlock-condacquire
- (int lockid, int mode)
- An LWLock was successfully acquired when the caller specified no
- waiting.
-
+ (LWLockId, LWLockMode)
+ Probe that fires when an LWLock was successfully acquired when the caller specified no waiting. arg0 is a predefined or dynamic ID defined in LWLockId enum. arg1 is a lock mode, either exclusive or shared.
lwlock-condacquire-fail
- (int lockid, int mode)
- An LWLock was not successfully acquired when the caller specified
- no waiting.
-
+ (LWLockId, LWLockMode)
+ Probe that fires when an LWLock was not successfully acquired when the caller specified no waiting. arg0 is a predefined or dynamic ID defined in LWLockId enum. arg1 is a lock mode, either exclusive or shared.
- lock-startwait
- (int locktag_field2, int lockmode)
- A request for a heavyweight lock (lmgr lock) has begun to wait
- because the lock is not available.
+ lock-wait-start
+ (unsigned int, LOCKMODE)
+ Probe that fires when a request for a heavyweight lock (lmgr lock) has begun to wait because the lock is not available. arg0 is the unique ID tag defined in LOCKTAG struct. arg1 is an integer indicating a lock type.
- lock-endwait
- (int locktag_field2, int lockmode)
- A request for a heavyweight lock (lmgr lock) has finished waiting
- (i.e., has acquired the lock).
+ lock-wait-done
+ (unsigned int, LOCKMODE)
+ Probe that fires when a request for a heavyweight lock (lmgr lock) has finished waiting (i.e., has acquired the lock). arg0 is the unique ID tag defined in LOCKTAG struct. arg1 is an integer indicating a lock type.
+
+
+ Defined Types Used in Probe Parameters
+
+
+
+ Type
+ Definition
+
+
+
+
+
+
+ LocalTransactionId
+ unsigned int
+
+
+ LWLockId
+ int
+
+
+ LWLockMode
+ int
+
+
+ LOCKMODE
+ int
+
+
+ BlockNumber
+ unsigned int
+
+
+ Oid
+ unsigned int
+
+
+ ForkNumber
+ int
+
+
+ bool
+ char
+
+
+
+
+
+
+
@@ -1181,6 +1477,10 @@ Total time (ns) 2
discussing information found using dynamic tracing, be sure to enclose
the script used to allow that too to be checked and discussed.
+
+ More example scripts can be found on
+ PgFoundry.
+
@@ -1207,7 +1507,7 @@ Total time (ns) 2
- Insert a one-line probe macros at the desired locations in the source code
+ Include pg_trace.h if it is not already presence and insert a one-line probe macros at the desired locations in the source code
@@ -1228,18 +1528,18 @@ Total time (ns) 2
- Name the probe transaction-start and give it a parameter of type integer (type of transaction ID)
+ Name the probe transaction-start and give it a parameter of type LocalTransactionId
- Add probe transaction__start(int);
to
+ Add probe transaction__start(LocalTransactionId);
to
src/backend/utils/probes.d, and it should look like the following:
provider postgresql {
...
- probe transaction__start(int);
+ probe transaction__start(LocalTransactionId);
...
};
@@ -1248,9 +1548,9 @@ provider postgresql {
- You should take care that the data types specified for the probe arguments
- match the data types of the variables used in the macro. Otherwise, you
- will get compilation errors.
+ 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.