1PERLDTRACE(1)          Perl Programmers Reference Guide          PERLDTRACE(1)
2
3
4

NAME

6       perldtrace - Perl's support for DTrace
7

SYNOPSIS

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
12        # perl -E 'sub outer { inner(@_) } sub inner { say shift } outer("hello")'
13        hello
14
15        (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

DESCRIPTION

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
34       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

HISTORY

42       5.10.1
43           Perl's initial DTrace support was added, providing "sub-entry" and
44           "sub-return" probes.
45
46       5.14.0
47           The "sub-entry" and "sub-return" probes gain a fourth argument: the
48           package name of the function.
49
50       5.16.0
51           The "phase-change" probe was added.
52
53       5.18.0
54           The "op-entry", "loading-file", and "loaded-file" probes were
55           added.
56

PROBES

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
64            :*perl*::sub-entry {
65                printf("%s::%s entered at %s line %d\n",
66                      copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
67            }
68
69       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
75            :*perl*::sub-return {
76                printf("%s::%s returned at %s line %d\n",
77                      copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
78            }
79
80       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
86            :*perl*::phase-change {
87                printf("Phase changed from %s to %s\n",
88                    copyinstr(arg1), copyinstr(arg0));
89            }
90
91       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
97            :*perl*::op-entry {
98                printf("About to execute opcode %s\n", copyinstr(arg0));
99            }
100
101       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
107            :*perl*:loading-file {
108                printf("About to load %s\n", copyinstr(arg0));
109            }
110
111       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
118            :*perl*:loaded-file {
119                printf("Successfully loaded %s\n", copyinstr(arg0));
120            }
121

EXAMPLES

123       Most frequently called functions
124            # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
125
126            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
137       Trace function calls
138            # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
139
140            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
155       Function calls during interpreter cleanup
156            # dtrace -Zn 'phase-change /copyinstr(arg0) == "END"/ { self->ending = 1 } sub-entry /self->ending/ { trace(copyinstr(arg0)) }'
157
158            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
165       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
168            lseek                                                           310
169            read                                                            374
170            stat64                                                         1056
171
172       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
175            warnings::unimport                                             4589
176            Exporter::Heavy::_rebuild_cache                                5039
177            Exporter::import                                              14578
178

REFERENCES

180       DTrace Dynamic Tracing Guide
181           <http://dtrace.org/guide/preface.html>
182
183       DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
184           <https://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/>
185

SEE ALSO

187       Devel::DTrace::Provider
188           This CPAN module lets you create application-level DTrace probes
189           written in Perl.
190

AUTHORS

192       Shawn M Moore "sartak@gmail.com"
193
194
195
196perl v5.38.2                      2023-11-30                     PERLDTRACE(1)
Impressum