8000 Add some documentation for DTrace support. Simon Riggs · postgrespro/postgres_cluster@606b10f · GitHub
[go: up one dir, main page]
Skip to content

Commit 606b10f

Browse files
tglsfdctglsfdc
committed
Add some documentation for DTrace support. Simon Riggs
1 parent d92b939 commit 606b10f

File tree

1 file changed

+278
-1
lines changed

1 file changed

+278
-1
lines changed

‎doc/src/sgml/monitoring.sgml

Lines changed: 278 additions & 1 deletion
815
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.39 2006/11/24 21:18:42 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/monitoring.sgml,v 1.40 2006/12/02 00:42:54 tgl Exp $ -->
22

33
<chapter id="monitoring">
44
<title>Monitoring Database Activity</title>
@@ -791,4 +791,281 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS procpid,
791791
<productname>PostgreSQL</productname>, refer to <xref linkend="mvcc">.
792792
</para>
793793
</sect1>
794+
795+
<sect1 id="dynamic-trace">
796+
<title>Dynamic Tracing</title>
797+
798+
<indexterm zone="dynamic-trace">
799+
<primary>DTrace</primary>
800+
</indexterm>
801+
802+
<para>
803+
<productname>PostgreSQL</productname> provides facilities to support
804+
dynamic tracing of the database server. This allows an external
805+
utility to be called at specific points in the code and thereby trace
806+
execution. Currently, this facility is primarily intended for use by
807+
database developers, as it requires substantial familiarity with the code.
808+
</para>
809+
810+
<para>
811+
A number of trace points, often called probes, are already inserted
812+
into the source code. By default these probes are disabled, and
813+
the user needs to explicitly tell the configure script to make the
814+
probes available in <productname>PostgreSQL</productname>.
+
</para>
816+
817+
<para>
818+
Currently, only the DTrace utility is supported, which is only available
819+
on Solaris Express and Solaris 10+. It is expected that DTrace will
820+
be available in the future on FreeBSD and Mac OS X.
821+
Supporting other dynamic tracing utilities is theoretically possible by
822+
changing the definitions for the <literal>PG_TRACE</> macros in
823+
<filename>src/include/pg_trace.h</>.
824+
</para>
825+
826+
<sect2 id="compiling-for-trace">
827+
<title>Compiling for Dynamic Trace</title>
828+
829+
<para>
830+
By default, trace points are disabled, so you will need to
831+
explicitly tell the configure script to make the probes available
832+
in <productname>PostgreSQL</productname>. To include DTrace support
833+
in a 32-bit binary, specify <option>--enable-dtrace</> to configure.
834+
For example:
835+
<programlisting>
836+
$ ./configure --enable-dtrace ...
837+
</programlisting>
838+
To include DTrace support in a 64-bit binary, specify
839+
<option>--enable-dtrace</>
840+
and <literal>DTRACEFLAGS="-64"</> to configure. For example,
841+
using the gcc compiler:
842+
<programlisting>
843+
$ ./configure CC='gcc -m64' --enable-dtrace DTRACEFLAGS='-64' ...
844+
</programlisting>
845+
Using Sun's compiler:
846+
<programlisting>
847+
$ ./configure CC='/path_to_sun_compiler/cc -xtarget=native64' --enable-dtrace DTRACEFLAGS='-64' ...
848+
</programlisting>
849+
</para>
850+
</sect2>
851+
852+
<sect2 id="trace-points">
853+
<title>Built-in Trace Points</title>
854+
855+
<para>
856+
A few standard trace points are provided in the source code
857+
(of course, more can be added as needed for a particular problem).
858+
These are:
859+
</para>
860+
861+
<table id="trace-point-table">
862+
<title>Built-in Trace Points</title>
863+
<tgroup cols="3">
864+
<thead>
865+
<row>
866+
<entry>Name</entry>
867+
<entry>Parameters</entry>
868+
<entry>Overview</entry>
869+
</row>
870+
</thead>
871+
872+
<tbody>
873+
<row>
874+
<entry>transaction__start</entry>
875+
<entry>(int transactionId)</entry>
876+
<entry>The start of a new transaction.</entry>
877+
</row>
878+
<row>
879+
<entry>transaction__commit</entry>
880+
<entry>(int transactionId)</entry>
881+
<entry>The successful completion of a transaction.</entry>
882+
</row>
883+
<row>
884+
<entry>transaction__abort</entry>
885+
<entry>(int transactionId)</entry>
886+
<entry>The unsuccessful completion of a transaction.</entry>
887+
</row>
888+
889+
<row>
890+
<entry>lwlock__acquire</entry>
891+
<entry>(int lockid, int mode)</entry>
892+
<entry>An LWLock has been acquired.</entry>
893+
</row>
894+
<row>
895+
<entry>lwlock__release</entry>
896+
<entry>(int lockid, int mode)</entry>
897+
<entry>An LWLock has been released.</entry>
898+
</row>
899+
<row>
900+
<entry>lwlock__startwait</entry>
901+
<entry>(int lockid, int mode)</entry>
902+
<entry>An LWLock was not immediately available and a backend
903+
has begun to wait for the lock to become available.
904+
</entry>
905+
</row>
906+
<row>
907+
<entry>lwlock__endwait</entry>
908+
<entry>(int lockid, int mode)</entry>
909+
<entry>A backend has been released from its wait for an LWLock.
910+
</entry>
911+
</row>
912+
<row>
913+
<entry>lwlock__condacquire</entry>
914+
<entry>(int lockid, int mode)</entry>
915+
<entry>An LWLock was successfully acquired when the caller specified no
916+
waiting.
917+
</entry>
918+
</row>
919+
<row>
920+
<entry>lwlock__condacquire__fail</entry>
921+
<entry>(int lockid, int mode)</entry>
922+
<entry>An LWLock was not successfully acquired when the caller specified
923+
no waiting.
924+
</entry>
925+
</row>
926+
<row>
927+
<entry>lock__startwait</entry>
928+
<entry>(int locktag_field2, int lockmode)</entry>
929+
<entry>A request for a heavyweight lock (lmgr lock) has begun to wait
930+
because the lock is not available.
931+
</entry>
932+
</row>
933+
<row>
934+
<entry>lock__endwait</entry>
935+
<entry>(int locktag_field2, int lockmode)</entry>
936+
<entry>A request for a heavyweight lock (lmgr lock) has finished waiting
937+
(i.e., has acquired the lock).
938+
</entry>
939+
</row>
940+
</tbody>
941+
</tgroup>
942+
</table>
943+
</sect2>
944+
945+
<sect2 id="using-trace-points">
946+
<title>Using Trace Points</title>
947+
948+
<para>
949+
The example below shows a DTrace script for analyzing transaction
950+
counts on the system, as an alternative to snapshotting
951+
<structname>pg_stat_database</> before and after a performance test.
952+
<programlisting>
953+
#!/usr/sbin/dtrace -qs
954+
955+
postgresql$1:::transaction-start
956+
{
957+
@start["Start"] = count();
958+
self->ts = timestamp;
959+
}
960+
961+
postgresql$1:::transaction-abort
962+
{
963+
@abort["Abort"] = count();
964+
}
965+
966+
postgresql$1:::transaction-commit
967+
/self->ts/
968+
{
969+
@commit["Commit"] = count();
970+
@time["Total time (ns)"] = sum(timestamp - self->ts);
971+
self->ts=0;
972+
}
973+
</programlisting>
974+
Note how the double underline in trace point names needs to
975+
be replaced by a hyphen when using D script.
976+
When executed, the example D script gives output such as:
977+
<programlisting>
978+
# ./txn_count.d `pgrep -n postgres`
979+
^C
980+
981+
Start 71
982+
Commit 70
983+
Abort 1
984+
Total time (ns) 2312105013
985+
</programlisting>
986+
</para>
987+
<para>
988+
You should remember that trace programs need to be carefully written and
989+
debugged prior to their use, otherwise the trace information collected may
990+
be meaningless. In most cases where problems are found it is the
991+
instrumentation that is at fault, not the underlying system. When
992+
discussing information found using dynamic tracing, be sure to enclose
993+
the script used to allow that too to be checked and discussed.
994+
</para>
995+
</sect2>
996+
997+
<sect2 id="defining-trace-points">
998+
<title>Defining Trace Points</title>
999+
1000+
<para>
1001+
New trace points can be defined within the code wherever the developer
1002+
desires, though this will require a re-compile.
1003+
</para>
1004+
1005+
<para>
1006+
A trace point can be inserted by using one of the
1007+
trace macros. These are chosen according to how many variables will
1008+
be made available for inspection at that trace point. Tracing the
1009+
occurrence of an event can be achieved with a single line, using
1010+
just the trace point name, e.g.
1011+
<programlisting>
1012+
PG_TRACE (my__new__trace__point);
1013+
</programlisting>
1014+
More complex trace points can be provided with one or more variables
1015+
for inspection by the dynamic tracing utility by using the
1016+
<literal>PG_TRACE</><replaceable>n</> macro that corresponds to the number
1017+
of parameters after the trace point name:
1018+
<programlisting>
1019+
PG_TRACE3 (my__complex__event, varX, varY, varZ);
1020+
</programlisting>
1021+
The definition of the transaction__start trace point is shown below:
1022+
<programlisting>
1023+
static void
1024+
StartTransaction(void)
1025+
{
1026+
...
1027+
1028+
/*
1029+
* generate a new transaction id
1030+
*/
1031+
s->transactionId = GetNewTransactionId(false);
1032+
1033+
XactLockTableInsert(s->transactionId);
1034+
1035+
PG_TRACE1(transaction__start, s->transactionId);
1036+
1037+
...
1038+
}
1039+
</programlisting>
1040+
Note how the transaction ID is made available to the dynamic tracing
1041+
utility.
1042+
</para>
1043+
1044+
<para>
1045+
The dynamic tracing utility may require you to further define these trace
1046+
points. For example, DTrace requires you to add new probes to the file
1047+
<filename>src/backend/utils/probes.d</> as shown here:
1048+
<programlisting>
1049+
provider postgresql {
1050+
...
1051+
probe transaction__start(int);
1052+
...
1053+
};
1054+
</programlisting>
1055+
</para>
1056+
1057+
<para>
1058+
You should take care that the datatypes specified for the probe arguments
1059+
match the datatypes of the variables used in the <literal>PG_TRACE</>
1060+
macro. This is not checked at compile time. You can check that your newly
1061+
added trace point is available by recompiling, then running the new binary,
1062+
and as root, executing a DTrace command such as:
1063+
<programlisting>
1064+
dtrace -l -n transaction-start
1065+
</programlisting>
1066+
</para>
1067+
</sect2>
1068+
1069+
</sect1>
1070+
7941071
</chapter>

0 commit comments

Comments
 (0)
0