Debian Codegraph @

upstream/debian-unstable/man1/perldtrace.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLDTRACE 1"
58 .TH PERLDTRACE 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perldtrace \- Perl's support for DTrace
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& # dtrace \-Zn \*(Aqperl::sub\-entry, perl::sub\-return { trace(copyinstr(arg0)) }\*(Aq
69 \& dtrace: description \*(Aqperl::sub\-entry, perl::sub\-return \*(Aq matched 10 probes
70 \&
71 \& # perl \-E \*(Aqsub outer { inner(@_) } sub inner { say shift } outer("hello")\*(Aq
72 \& hello
73 \&
74 \& (dtrace output)
75 \& CPU ID FUNCTION:NAME
76 \& 0 75915 Perl_pp_entersub:sub\-entry BEGIN
77 \& 0 75915 Perl_pp_entersub:sub\-entry import
78 \& 0 75922 Perl_pp_leavesub:sub\-return import
79 \& 0 75922 Perl_pp_leavesub:sub\-return BEGIN
80 \& 0 75915 Perl_pp_entersub:sub\-entry outer
81 \& 0 75915 Perl_pp_entersub:sub\-entry inner
82 \& 0 75922 Perl_pp_leavesub:sub\-return inner
83 \& 0 75922 Perl_pp_leavesub:sub\-return outer
84 .Ve
85 .SH DESCRIPTION
86 .IX Header "DESCRIPTION"
87 DTrace is a framework for comprehensive system\- and application-level
88 tracing. Perl is a DTrace \fIprovider\fR, meaning it exposes several
89 \&\fIprobes\fR for instrumentation. You can use these in conjunction
90 with kernel-level probes, as well as probes from other providers
91 such as MySQL, in order to diagnose software defects, or even just
92 your application's bottlenecks.
93 .PP
94 Perl must be compiled with the \f(CW\*(C`\-Dusedtrace\*(C'\fR option in order to
95 make use of the provided probes. While DTrace aims to have no
96 overhead when its instrumentation is not active, Perl's support
97 itself cannot uphold that guarantee, so it is built without DTrace
98 probes under most systems. One notable exception is that Mac OS X
99 ships a \fI/usr/bin/perl\fR with DTrace support enabled.
100 .SH HISTORY
101 .IX Header "HISTORY"
102 .IP 5.10.1 4
103 .IX Item "5.10.1"
104 Perl's initial DTrace support was added, providing \f(CW\*(C`sub\-entry\*(C'\fR and
105 \&\f(CW\*(C`sub\-return\*(C'\fR probes.
106 .IP 5.14.0 4
107 .IX Item "5.14.0"
108 The \f(CW\*(C`sub\-entry\*(C'\fR and \f(CW\*(C`sub\-return\*(C'\fR probes gain a fourth argument: the
109 package name of the function.
110 .IP 5.16.0 4
111 .IX Item "5.16.0"
112 The \f(CW\*(C`phase\-change\*(C'\fR probe was added.
113 .IP 5.18.0 4
114 .IX Item "5.18.0"
115 The \f(CW\*(C`op\-entry\*(C'\fR, \f(CW\*(C`loading\-file\*(C'\fR, and \f(CW\*(C`loaded\-file\*(C'\fR probes were added.
116 .SH PROBES
117 .IX Header "PROBES"
118 .IP "sub\-entry(SUBNAME, FILE, LINE, PACKAGE)" 4
119 .IX Item "sub-entry(SUBNAME, FILE, LINE, PACKAGE)"
120 Traces the entry of any subroutine. Note that all of the variables
121 refer to the subroutine that is being invoked; there is currently
122 no way to get ahold of any information about the subroutine's
123 \&\fIcaller\fR from a DTrace action.
124 .Sp
125 .Vb 4
126 \& :*perl*::sub\-entry {
127 \& printf("%s::%s entered at %s line %d\en",
128 \& copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
129 \& }
130 .Ve
131 .IP "sub\-return(SUBNAME, FILE, LINE, PACKAGE)" 4
132 .IX Item "sub-return(SUBNAME, FILE, LINE, PACKAGE)"
133 Traces the exit of any subroutine. Note that all of the variables
134 refer to the subroutine that is returning; there is currently no
135 way to get ahold of any information about the subroutine's \fIcaller\fR
136 from a DTrace action.
137 .Sp
138 .Vb 4
139 \& :*perl*::sub\-return {
140 \& printf("%s::%s returned at %s line %d\en",
141 \& copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
142 \& }
143 .Ve
144 .IP "phase\-change(NEWPHASE, OLDPHASE)" 4
145 .IX Item "phase-change(NEWPHASE, OLDPHASE)"
146 Traces changes to Perl's interpreter state. You can internalize this
147 as tracing changes to Perl's \f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR variable, especially
148 since the values for \f(CW\*(C`NEWPHASE\*(C'\fR and \f(CW\*(C`OLDPHASE\*(C'\fR are the strings that
149 \&\f(CW\*(C`${^GLOBAL_PHASE}\*(C'\fR reports.
150 .Sp
151 .Vb 4
152 \& :*perl*::phase\-change {
153 \& printf("Phase changed from %s to %s\en",
154 \& copyinstr(arg1), copyinstr(arg0));
155 \& }
156 .Ve
157 .IP op\-entry(OPNAME) 4
158 .IX Item "op-entry(OPNAME)"
159 Traces the execution of each opcode in the Perl runloop. This probe
160 is fired before the opcode is executed. When the Perl debugger is
161 enabled, the DTrace probe is fired \fIafter\fR the debugger hooks (but
162 still before the opcode itself is executed).
163 .Sp
164 .Vb 3
165 \& :*perl*::op\-entry {
166 \& printf("About to execute opcode %s\en", copyinstr(arg0));
167 \& }
168 .Ve
169 .IP loading\-file(FILENAME) 4
170 .IX Item "loading-file(FILENAME)"
171 Fires when Perl is about to load an individual file, whether from
172 \&\f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`do\*(C'\fR. This probe fires before the file is
173 read from disk. The filename argument is converted to local filesystem
174 paths instead of providing \f(CW\*(C`Module::Name\*(C'\fR\-style names.
175 .Sp
176 .Vb 3
177 \& :*perl*:loading\-file {
178 \& printf("About to load %s\en", copyinstr(arg0));
179 \& }
180 .Ve
181 .IP loaded\-file(FILENAME) 4
182 .IX Item "loaded-file(FILENAME)"
183 Fires when Perl has successfully loaded an individual file, whether
184 from \f(CW\*(C`use\*(C'\fR, \f(CW\*(C`require\*(C'\fR, or \f(CW\*(C`do\*(C'\fR. This probe fires after the file
185 is read from disk and its contents evaluated. The filename argument
186 is converted to local filesystem paths instead of providing
187 \&\f(CW\*(C`Module::Name\*(C'\fR\-style names.
188 .Sp
189 .Vb 3
190 \& :*perl*:loaded\-file {
191 \& printf("Successfully loaded %s\en", copyinstr(arg0));
192 \& }
193 .Ve
194 .SH EXAMPLES
195 .IX Header "EXAMPLES"
196 .IP "Most frequently called functions" 4
197 .IX Item "Most frequently called functions"
198 .Vb 1
199 \& # dtrace \-qZn \*(Aqsub\-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}\*(Aq
200 \&
201 \& Class::MOP::Attribute::slots 400
202 \& Try::Tiny::catch 411
203 \& Try::Tiny::try 411
204 \& Class::MOP::Instance::inline_slot_access 451
205 \& Class::MOP::Class::Immutable::Trait:::around 472
206 \& Class::MOP::Mixin::AttributeCore::has_initializer 496
207 \& Class::MOP::Method::Wrapped::_\|_ANON_\|_ 544
208 \& Class::MOP::Package::_package_stash 737
209 \& Class::MOP::Class::initialize 1128
210 \& Class::MOP::get_metaclass_by_name 1204
211 .Ve
212 .IP "Trace function calls" 4
213 .IX Item "Trace function calls"
214 .Vb 1
215 \& # dtrace \-qFZn \*(Aqsub\-entry, sub\-return { trace(copyinstr(arg0)) }\*(Aq
216 \&
217 \& 0 \-> Perl_pp_entersub BEGIN
218 \& 0 <\- Perl_pp_leavesub BEGIN
219 \& 0 \-> Perl_pp_entersub BEGIN
220 \& 0 \-> Perl_pp_entersub import
221 \& 0 <\- Perl_pp_leavesub import
222 \& 0 <\- Perl_pp_leavesub BEGIN
223 \& 0 \-> Perl_pp_entersub BEGIN
224 \& 0 \-> Perl_pp_entersub dress
225 \& 0 <\- Perl_pp_leavesub dress
226 \& 0 \-> Perl_pp_entersub dirty
227 \& 0 <\- Perl_pp_leavesub dirty
228 \& 0 \-> Perl_pp_entersub whiten
229 \& 0 <\- Perl_pp_leavesub whiten
230 \& 0 <\- Perl_dounwind BEGIN
231 .Ve
232 .IP "Function calls during interpreter cleanup" 4
233 .IX Item "Function calls during interpreter cleanup"
234 .Vb 1
235 \& # dtrace \-Zn \*(Aqphase\-change /copyinstr(arg0) == "END"/ { self\->ending = 1 } sub\-entry /self\->ending/ { trace(copyinstr(arg0)) }\*(Aq
236 \&
237 \& CPU ID FUNCTION:NAME
238 \& 1 77214 Perl_pp_entersub:sub\-entry END
239 \& 1 77214 Perl_pp_entersub:sub\-entry END
240 \& 1 77214 Perl_pp_entersub:sub\-entry cleanup
241 \& 1 77214 Perl_pp_entersub:sub\-entry _force_writable
242 \& 1 77214 Perl_pp_entersub:sub\-entry _force_writable
243 .Ve
244 .IP "System calls at compile time" 4
245 .IX Item "System calls at compile time"
246 .Vb 1
247 \& # dtrace \-qZn \*(Aqphase\-change /copyinstr(arg0) == "START"/ { self\->interesting = 1 } phase\-change /copyinstr(arg0) == "RUN"/ { self\->interesting = 0 } syscall::: /self\->interesting/ { @[probefunc] = count() } END { trunc(@, 3) }\*(Aq
248 \&
249 \& lseek 310
250 \& read 374
251 \& stat64 1056
252 .Ve
253 .IP "Perl functions that execute the most opcodes" 4
254 .IX Item "Perl functions that execute the most opcodes"
255 .Vb 1
256 \& # dtrace \-qZn \*(Aqsub\-entry { self\->fqn = strjoin(copyinstr(arg3), strjoin("::", copyinstr(arg0))) } op\-entry /self\->fqn != ""/ { @[self\->fqn] = count() } END { trunc(@, 3) }\*(Aq
257 \&
258 \& warnings::unimport 4589
259 \& Exporter::Heavy::_rebuild_cache 5039
260 \& Exporter::import 14578
261 .Ve
262 .SH REFERENCES
263 .IX Header "REFERENCES"
264 .IP "DTrace Dynamic Tracing Guide" 4
265 .IX Item "DTrace Dynamic Tracing Guide"
266 <https://illumos.org/books/dtrace/preface.html>
267 .IP "DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD" 4
268 .IX Item "DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD"
269 <https://www.amazon.com/DTrace\-Dynamic\-Tracing\-Solaris\-FreeBSD/dp/0132091518/>
270 .SH "SEE ALSO"
271 .IX Header "SEE ALSO"
272 .IP Devel::DTrace::Provider 4
273 .IX Item "Devel::DTrace::Provider"
274 This CPAN module lets you create application-level DTrace probes written in
275 Perl.
276 .SH AUTHORS
277 .IX Header "AUTHORS"
278 Shawn M Moore \f(CW\*(C`[email protected]\*(C'\fR