1PERLDTRACE(1) Perl Programmers Reference Guide PERLDTRACE(1)
2
6 perldtrace - Perl's support for DTrace
7
9 # dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'
10 dtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes
11 # perl -E 'sub outer { inner(@_) } sub inner { say shift } outer("hello")'
13 hello
14 (dtrace output)
16 CPU ID FUNCTION:NAME
17 0 75915 Perl_pp_entersub:sub-entry BEGIN
18 0 75915 Perl_pp_entersub:sub-entry import
19 0 75922 Perl_pp_leavesub:sub-return import
20 0 75922 Perl_pp_leavesub:sub-return BEGIN
21 0 75915 Perl_pp_entersub:sub-entry outer
22 0 75915 Perl_pp_entersub:sub-entry inner
23 0 75922 Perl_pp_leavesub:sub-return inner
24 0 75922 Perl_pp_leavesub:sub-return outer
25
27 DTrace is a framework for comprehensive system- and application-level
28 tracing. Perl is a DTrace provider, meaning it exposes several probes
29 for instrumentation. You can use these in conjunction with kernel-level
30 probes, as well as probes from other providers such as MySQL, in order
31 to diagnose software defects, or even just your application's
32 bottlenecks.
33 Perl must be compiled with the "-Dusedtrace" option in order to make
35 use of the provided probes. While DTrace aims to have no overhead when
36 its instrumentation is not active, Perl's support itself cannot uphold
37 that guarantee, so it is built without DTrace probes under most
38 systems. One notable exception is that Mac OS X ships a /usr/bin/perl
39 with DTrace support enabled.
40
42 5.10.1
43 Perl's initial DTrace support was added, providing "sub-entry" and
44 "sub-return" probes.
45 5.14.0
47 The "sub-entry" and "sub-return" probes gain a fourth argument: the
48 package name of the function.
49 5.16.0
51 The "phase-change" probe was added.
52 5.18.0
54 The "op-entry", "loading-file", and "loaded-file" probes were
55 added.
56
58 sub-entry(SUBNAME, FILE, LINE, PACKAGE)
59 Traces the entry of any subroutine. Note that all of the variables
60 refer to the subroutine that is being invoked; there is currently
61 no way to get ahold of any information about the subroutine's
62 caller from a DTrace action.
63 :*perl*::sub-entry {
65 printf("%s::%s entered at %s line %d\n",
66 copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
67 }
68 sub-return(SUBNAME, FILE, LINE, PACKAGE)
70 Traces the exit of any subroutine. Note that all of the variables
71 refer to the subroutine that is returning; there is currently no
72 way to get ahold of any information about the subroutine's caller
73 from a DTrace action.
74 :*perl*::sub-return {
76 printf("%s::%s returned at %s line %d\n",
77 copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
78 }
79 phase-change(NEWPHASE, OLDPHASE)
81 Traces changes to Perl's interpreter state. You can internalize
82 this as tracing changes to Perl's "${^GLOBAL_PHASE}" variable,
83 especially since the values for "NEWPHASE" and "OLDPHASE" are the
84 strings that "${^GLOBAL_PHASE}" reports.
85 :*perl*::phase-change {
87 printf("Phase changed from %s to %s\n",
88 copyinstr(arg1), copyinstr(arg0));
89 }
90 op-entry(OPNAME)
92 Traces the execution of each opcode in the Perl runloop. This probe
93 is fired before the opcode is executed. When the Perl debugger is
94 enabled, the DTrace probe is fired after the debugger hooks (but
95 still before the opcode itself is executed).
96 :*perl*::op-entry {
98 printf("About to execute opcode %s\n", copyinstr(arg0));
99 }
100 loading-file(FILENAME)
102 Fires when Perl is about to load an individual file, whether from
103 "use", "require", or "do". This probe fires before the file is read
104 from disk. The filename argument is converted to local filesystem
105 paths instead of providing "Module::Name"-style names.
106 :*perl*:loading-file {
108 printf("About to load %s\n", copyinstr(arg0));
109 }
110 loaded-file(FILENAME)
112 Fires when Perl has successfully loaded an individual file, whether
113 from "use", "require", or "do". This probe fires after the file is
114 read from disk and its contents evaluated. The filename argument is
115 converted to local filesystem paths instead of providing
116 "Module::Name"-style names.
117 :*perl*:loaded-file {
119 printf("Successfully loaded %s\n", copyinstr(arg0));
120 }
121
123 Most frequently called functions
124 # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
125 Class::MOP::Attribute::slots 400
127 Try::Tiny::catch 411
128 Try::Tiny::try 411
129 Class::MOP::Instance::inline_slot_access 451
130 Class::MOP::Class::Immutable::Trait:::around 472
131 Class::MOP::Mixin::AttributeCore::has_initializer 496
132 Class::MOP::Method::Wrapped::__ANON__ 544
133 Class::MOP::Package::_package_stash 737
134 Class::MOP::Class::initialize 1128
135 Class::MOP::get_metaclass_by_name 1204
136 Trace function calls
138 # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
139 0 -> Perl_pp_entersub BEGIN
141 0 <- Perl_pp_leavesub BEGIN
142 0 -> Perl_pp_entersub BEGIN
143 0 -> Perl_pp_entersub import
144 0 <- Perl_pp_leavesub import
145 0 <- Perl_pp_leavesub BEGIN
146 0 -> Perl_pp_entersub BEGIN
147 0 -> Perl_pp_entersub dress
148 0 <- Perl_pp_leavesub dress
149 0 -> Perl_pp_entersub dirty
150 0 <- Perl_pp_leavesub dirty
151 0 -> Perl_pp_entersub whiten
152 0 <- Perl_pp_leavesub whiten
153 0 <- Perl_dounwind BEGIN
154 Function calls during interpreter cleanup
156 # dtrace -Zn 'phase-change /copyinstr(arg0) == "END"/ { self->ending = 1 } sub-entry /self->ending/ { trace(copyinstr(arg0)) }'
157 CPU ID FUNCTION:NAME
159 1 77214 Perl_pp_entersub:sub-entry END
160 1 77214 Perl_pp_entersub:sub-entry END
161 1 77214 Perl_pp_entersub:sub-entry cleanup
162 1 77214 Perl_pp_entersub:sub-entry _force_writable
163 1 77214 Perl_pp_entersub:sub-entry _force_writable
164 System calls at compile time
166 # 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) }'
167 lseek 310
169 read 374
170 stat64 1056
171 Perl functions that execute the most opcodes
173 # dtrace -qZn 'sub-entry { self->fqn = strjoin(copyinstr(arg3), strjoin("::", copyinstr(arg0))) } op-entry /self->fqn != ""/ { @[self->fqn] = count() } END { trunc(@, 3) }'
174 warnings::unimport 4589
176 Exporter::Heavy::_rebuild_cache 5039
177 Exporter::import 14578
178
180 DTrace Dynamic Tracing Guide
181 <http://dtrace.org/guide/preface.html>
182 DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
184 <https://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/>
185
187 Devel::DTrace::Provider
188 This CPAN module lets you create application-level DTrace probes
189 written in Perl.
190
192 Shawn M Moore "sartak@gmail.com"
193perl v5.38.2 2023-11-30 PERLDTRACE(1)