Debian Codegraph @

upstream/opensuse-tumbleweed/man1/perldtrace.1

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