This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
New document for perldtrace
[perl5.git] / pod / perldtrace.pod
1 =head1 NAME
2
3 perldtrace - 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
26 DTrace is a framework for comprehensive system- and application-level
27 tracing. Perl is a DTrace I<provider>, meaning it exposes several
28 I<probes> for instrumentation. You can use these in conjunction
29 with kernel-level probes, as well as probes from other providers
30 such as MySQL, in order to diagnose software defects, or even just
31 your application's bottlenecks.
32
33 Perl must be compiled with the C<-Dusedtrace> option in order to
34 make use of the provided probes. While DTrace aims to have no
35 overhead when its instrumentation is not active, Perl's support
36 itself cannot uphold that guarantee, so it is built without DTrace
37 probes under most systems. One notable exception is that Mac OS X
38 ships a F</usr/bin/perl> with DTrace support enabled.
39
40 =head1 HISTORY
41
42 =over 4
43
44 =item 5.10.1
45
46 Perl's initial DTrace support was added, providing C<sub-entry> and
47 C<sub-return> probes.
48
49 =item 5.14.0
50
51 The C<sub-entry> and C<sub-return> probes gain a fourth argument: the
52 package name of the function.
53
54 =back
55
56 =head1 PROBES
57
58 =over 4
59
60 =item sub-entry(SUBNAME, FILE, LINE, PACKAGE)
61
62 Traces the entry of any subroutine. Note that all of the variables
63 refer to the subroutine that is being invoked; there is currently
64 no way to get ahold of any information about the subroutine's
65 I<caller> from a DTrace action.
66
67     :*perl*::sub-entry {
68         printf("%s::%s entered at %s line %d\n",
69                copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg0);
70     }
71
72 =item sub-return(SUBNAME, FILE, LINE, PACKAGE)
73
74 Traces the exit of any subroutine. Note that all of the variables
75 refer to the subroutine that is returning; there is currently no
76 way to get ahold of any information about the subroutine's I<caller>
77 from a DTrace action.
78
79     :*perl*::sub-return {
80         printf("%s::%s returned at %s line %d\n",
81                copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg0);
82     }
83
84 =back
85
86 =head1 EXAMPLES
87
88 =over 4
89
90 =item Most frequently called functions
91
92     # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
93
94     Class::MOP::Attribute::slots                                    400
95     Try::Tiny::catch                                                411
96     Try::Tiny::try                                                  411
97     Class::MOP::Instance::inline_slot_access                        451
98     Class::MOP::Class::Immutable::Trait:::around                    472
99     Class::MOP::Mixin::AttributeCore::has_initializer               496
100     Class::MOP::Method::Wrapped::__ANON__                           544
101     Class::MOP::Package::_package_stash                             737
102     Class::MOP::Class::initialize                                  1128
103     Class::MOP::get_metaclass_by_name                              1204
104
105 =item Trace function calls
106
107     # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
108
109     0  -> Perl_pp_entersub                        BEGIN                            
110     0  <- Perl_pp_leavesub                        BEGIN                            
111     0  -> Perl_pp_entersub                        BEGIN                            
112     0    -> Perl_pp_entersub                      import                           
113     0    <- Perl_pp_leavesub                      import                           
114     0  <- Perl_pp_leavesub                        BEGIN                            
115     0  -> Perl_pp_entersub                        BEGIN                            
116     0    -> Perl_pp_entersub                      dress                            
117     0    <- Perl_pp_leavesub                      dress                            
118     0    -> Perl_pp_entersub                      dirty                            
119     0    <- Perl_pp_leavesub                      dirty                            
120     0    -> Perl_pp_entersub                      whiten                           
121     0    <- Perl_pp_leavesub                      whiten                           
122     0  <- Perl_dounwind                           BEGIN 
123
124 =back
125
126 =head1 REFERENCES
127
128 =over 4
129
130 =item DTrace User Guide
131
132 L<http://download.oracle.com/docs/cd/E19082-01/819-3620/index.html>
133
134 =item DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
135
136 L<http://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/>
137
138 =back
139
140 =head1 AUTHORS
141
142 Shawn M Moore C<sartak@gmail.com>
143
144 =cut