This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Document and test the phase-change probe
[perl5.git] / pod / perldtrace.pod
CommitLineData
f993ad5b
SM
1=head1 NAME
2
3perldtrace - Perl's support for DTrace
4
5=head1 SYNOPSIS
6
7 # dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'
8 dtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes
9
10 # perl -E 'sub outer { inner(@_) } sub inner { say shift } outer("hello")'
11 hello
12
13 (dtrace output)
14 CPU ID FUNCTION:NAME
15 0 75915 Perl_pp_entersub:sub-entry BEGIN
16 0 75915 Perl_pp_entersub:sub-entry import
17 0 75922 Perl_pp_leavesub:sub-return import
18 0 75922 Perl_pp_leavesub:sub-return BEGIN
19 0 75915 Perl_pp_entersub:sub-entry outer
20 0 75915 Perl_pp_entersub:sub-entry inner
21 0 75922 Perl_pp_leavesub:sub-return inner
22 0 75922 Perl_pp_leavesub:sub-return outer
23
24=head1 DESCRIPTION
25
26DTrace is a framework for comprehensive system- and application-level
27tracing. Perl is a DTrace I<provider>, meaning it exposes several
28I<probes> for instrumentation. You can use these in conjunction
29with kernel-level probes, as well as probes from other providers
30such as MySQL, in order to diagnose software defects, or even just
31your application's bottlenecks.
32
33Perl must be compiled with the C<-Dusedtrace> option in order to
34make use of the provided probes. While DTrace aims to have no
35overhead when its instrumentation is not active, Perl's support
36itself cannot uphold that guarantee, so it is built without DTrace
37probes under most systems. One notable exception is that Mac OS X
38ships a F</usr/bin/perl> with DTrace support enabled.
39
40=head1 HISTORY
41
42=over 4
43
44=item 5.10.1
45
46Perl's initial DTrace support was added, providing C<sub-entry> and
47C<sub-return> probes.
48
49=item 5.14.0
50
51The C<sub-entry> and C<sub-return> probes gain a fourth argument: the
52package name of the function.
53
2b679393
SM
54=item 5.16.0
55
56The C<phase-change> probe was added.
57
f993ad5b
SM
58=back
59
60=head1 PROBES
61
62=over 4
63
64=item sub-entry(SUBNAME, FILE, LINE, PACKAGE)
65
66Traces the entry of any subroutine. Note that all of the variables
67refer to the subroutine that is being invoked; there is currently
68no way to get ahold of any information about the subroutine's
69I<caller> from a DTrace action.
70
71 :*perl*::sub-entry {
72 printf("%s::%s entered at %s line %d\n",
73 copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg0);
74 }
75
76=item sub-return(SUBNAME, FILE, LINE, PACKAGE)
77
78Traces the exit of any subroutine. Note that all of the variables
79refer to the subroutine that is returning; there is currently no
80way to get ahold of any information about the subroutine's I<caller>
81from a DTrace action.
82
83 :*perl*::sub-return {
84 printf("%s::%s returned at %s line %d\n",
85 copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg0);
86 }
87
2b679393
SM
88=item phase-change(NEWPHASE, OLDPHASE)
89
90Traces changes to Perl's interpreter state. You can internalize this
91as tracing changes to Perl's C<${^GLOBAL_PHASE}> variable, especially
92since the values for C<NEWPHASE> and C<OLDPHASE> are the strings that
93C<${^GLOBAL_PHASE}> reports.
94
95 :*perl*::phase-change {
96 printf("Phase changed from %s to %s\n",
97 copyinstr(arg1), copyinstr(arg0));
98 }
99
f993ad5b
SM
100=back
101
102=head1 EXAMPLES
103
104=over 4
105
106=item Most frequently called functions
107
108 # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
109
110 Class::MOP::Attribute::slots 400
111 Try::Tiny::catch 411
112 Try::Tiny::try 411
113 Class::MOP::Instance::inline_slot_access 451
114 Class::MOP::Class::Immutable::Trait:::around 472
115 Class::MOP::Mixin::AttributeCore::has_initializer 496
116 Class::MOP::Method::Wrapped::__ANON__ 544
117 Class::MOP::Package::_package_stash 737
118 Class::MOP::Class::initialize 1128
119 Class::MOP::get_metaclass_by_name 1204
120
121=item Trace function calls
122
123 # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
124
2b679393
SM
125 0 -> Perl_pp_entersub BEGIN
126 0 <- Perl_pp_leavesub BEGIN
127 0 -> Perl_pp_entersub BEGIN
128 0 -> Perl_pp_entersub import
129 0 <- Perl_pp_leavesub import
130 0 <- Perl_pp_leavesub BEGIN
131 0 -> Perl_pp_entersub BEGIN
132 0 -> Perl_pp_entersub dress
133 0 <- Perl_pp_leavesub dress
134 0 -> Perl_pp_entersub dirty
135 0 <- Perl_pp_leavesub dirty
136 0 -> Perl_pp_entersub whiten
137 0 <- Perl_pp_leavesub whiten
138 0 <- Perl_dounwind BEGIN
139
140=item Function calls during interpreter cleanup
141
142 # dtrace -Zn 'phase-change /copyinstr(arg0) == "END"/ { self->ending = 1 } sub-entry /self->ending/ { trace(copyinstr(arg0)) }'
143
144 CPU ID FUNCTION:NAME
145 1 77214 Perl_pp_entersub:sub-entry END
146 1 77214 Perl_pp_entersub:sub-entry END
147 1 77214 Perl_pp_entersub:sub-entry cleanup
148 1 77214 Perl_pp_entersub:sub-entry _force_writable
149 1 77214 Perl_pp_entersub:sub-entry _force_writable
150
151=item System calls at compile time
152
153 # dtrace -qZn 'phase-change /copyinstr(arg0) == "START"/ { self->interesting = 1 } phase-change /copyinstr(arg0) == "RUN"/ { self->interesting = 0 } syscall::: /self->interesting/ { @[probefunc] = count() } END { trunc(@, 3) }'
154
155 lseek 310
156 read 374
157 stat64 1056
f993ad5b
SM
158
159=back
160
161=head1 REFERENCES
162
163=over 4
164
165=item DTrace User Guide
166
167L<http://download.oracle.com/docs/cd/E19082-01/819-3620/index.html>
168
169=item DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
170
171L<http://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/>
172
173=back
174
175=head1 AUTHORS
176
177Shawn M Moore C<sartak@gmail.com>
178
179=cut