This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Finalize perldelta for 5.33.5
[perl5.git] / pod / perldtrace.pod
index 2654417..e0280d2 100644 (file)
@@ -4,22 +4,22 @@ perldtrace - Perl's support for DTrace
 
 =head1 SYNOPSIS
 
   # dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'
   dtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes
-
   # perl -E 'sub outer { inner(@_) } sub inner { say shift } outer("hello")'
   hello
-
   (dtrace output)
   CPU     ID                    FUNCTION:NAME
-      0  75915       Perl_pp_entersub:sub-entry   BEGIN
-      0  75915       Perl_pp_entersub:sub-entry   import
-      0  75922      Perl_pp_leavesub:sub-return   import
-      0  75922      Perl_pp_leavesub:sub-return   BEGIN
-      0  75915       Perl_pp_entersub:sub-entry   outer
-      0  75915       Perl_pp_entersub:sub-entry   inner
-      0  75922      Perl_pp_leavesub:sub-return   inner
-      0  75922      Perl_pp_leavesub:sub-return   outer
+ # dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'
+ dtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes
+
+ # perl -E 'sub outer { inner(@_) } sub inner { say shift } outer("hello")'
+ hello
+
+ (dtrace output)
+ CPU     ID                    FUNCTION:NAME
+   0  75915       Perl_pp_entersub:sub-entry   BEGIN
+   0  75915       Perl_pp_entersub:sub-entry   import
+   0  75922      Perl_pp_leavesub:sub-return   import
+   0  75922      Perl_pp_leavesub:sub-return   BEGIN
+   0  75915       Perl_pp_entersub:sub-entry   outer
+   0  75915       Perl_pp_entersub:sub-entry   inner
+   0  75922      Perl_pp_leavesub:sub-return   inner
+   0  75922      Perl_pp_leavesub:sub-return   outer
 
 =head1 DESCRIPTION
 
@@ -51,6 +51,14 @@ C<sub-return> probes.
 The C<sub-entry> and C<sub-return> probes gain a fourth argument: the
 package name of the function.
 
+=item 5.16.0
+
+The C<phase-change> probe was added.
+
+=item 5.18.0
+
+The C<op-entry>, C<loading-file>, and C<loaded-file> probes were added.
+
 =back
 
 =head1 PROBES
@@ -64,10 +72,10 @@ refer to the subroutine that is being invoked; there is currently
 no way to get ahold of any information about the subroutine's
 I<caller> from a DTrace action.
 
   :*perl*::sub-entry {
-        printf("%s::%s entered at %s line %d\n",
-               copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg0);
   }
+ :*perl*::sub-entry {
+     printf("%s::%s entered at %s line %d\n",
+           copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+ }
 
 =item sub-return(SUBNAME, FILE, LINE, PACKAGE)
 
@@ -76,10 +84,56 @@ refer to the subroutine that is returning; there is currently no
 way to get ahold of any information about the subroutine's I<caller>
 from a DTrace action.
 
-    :*perl*::sub-return {
-        printf("%s::%s returned at %s line %d\n",
-               copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg0);
-    }
+ :*perl*::sub-return {
+     printf("%s::%s returned at %s line %d\n",
+           copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+ }
+
+=item phase-change(NEWPHASE, OLDPHASE)
+
+Traces changes to Perl's interpreter state. You can internalize this
+as tracing changes to Perl's C<${^GLOBAL_PHASE}> variable, especially
+since the values for C<NEWPHASE> and C<OLDPHASE> are the strings that
+C<${^GLOBAL_PHASE}> reports.
+
+ :*perl*::phase-change {
+     printf("Phase changed from %s to %s\n",
+         copyinstr(arg1), copyinstr(arg0));
+ }
+
+=item op-entry(OPNAME)
+
+Traces the execution of each opcode in the Perl runloop. This probe
+is fired before the opcode is executed. When the Perl debugger is
+enabled, the DTrace probe is fired I<after> the debugger hooks (but
+still before the opcode itself is executed).
+
+ :*perl*::op-entry {
+     printf("About to execute opcode %s\n", copyinstr(arg0));
+ }
+
+=item loading-file(FILENAME)
+
+Fires when Perl is about to load an individual file, whether from
+C<use>, C<require>, or C<do>. This probe fires before the file is
+read from disk. The filename argument is converted to local filesystem
+paths instead of providing C<Module::Name>-style names.
+
+ :*perl*:loading-file {
+     printf("About to load %s\n", copyinstr(arg0));
+ }
+
+=item loaded-file(FILENAME)
+
+Fires when Perl has successfully loaded an individual file, whether
+from C<use>, C<require>, or C<do>. This probe fires after the file
+is read from disk and its contents evaluated. The filename argument
+is converted to local filesystem paths instead of providing
+C<Module::Name>-style names.
+
+ :*perl*:loaded-file {
+     printf("Successfully loaded %s\n", copyinstr(arg0));
+ }
 
 =back
 
@@ -89,37 +143,64 @@ from a DTrace action.
 
 =item Most frequently called functions
 
   # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
+ # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
 
   Class::MOP::Attribute::slots                                    400
   Try::Tiny::catch                                                411
   Try::Tiny::try                                                  411
   Class::MOP::Instance::inline_slot_access                        451
   Class::MOP::Class::Immutable::Trait:::around                    472
   Class::MOP::Mixin::AttributeCore::has_initializer               496
   Class::MOP::Method::Wrapped::__ANON__                           544
   Class::MOP::Package::_package_stash                             737
   Class::MOP::Class::initialize                                  1128
   Class::MOP::get_metaclass_by_name                              1204
+ Class::MOP::Attribute::slots                                    400
+ Try::Tiny::catch                                                411
+ Try::Tiny::try                                                  411
+ Class::MOP::Instance::inline_slot_access                        451
+ Class::MOP::Class::Immutable::Trait:::around                    472
+ Class::MOP::Mixin::AttributeCore::has_initializer               496
+ Class::MOP::Method::Wrapped::__ANON__                           544
+ Class::MOP::Package::_package_stash                             737
+ Class::MOP::Class::initialize                                  1128
+ Class::MOP::get_metaclass_by_name                              1204
 
 =item Trace function calls
 
-    # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
-
-    0  -> Perl_pp_entersub                        BEGIN                            
-    0  <- Perl_pp_leavesub                        BEGIN                            
-    0  -> Perl_pp_entersub                        BEGIN                            
-    0    -> Perl_pp_entersub                      import                           
-    0    <- Perl_pp_leavesub                      import                           
-    0  <- Perl_pp_leavesub                        BEGIN                            
-    0  -> Perl_pp_entersub                        BEGIN                            
-    0    -> Perl_pp_entersub                      dress                            
-    0    <- Perl_pp_leavesub                      dress                            
-    0    -> Perl_pp_entersub                      dirty                            
-    0    <- Perl_pp_leavesub                      dirty                            
-    0    -> Perl_pp_entersub                      whiten                           
-    0    <- Perl_pp_leavesub                      whiten                           
-    0  <- Perl_dounwind                           BEGIN 
+ # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
+
+ 0  -> Perl_pp_entersub                        BEGIN
+ 0  <- Perl_pp_leavesub                        BEGIN
+ 0  -> Perl_pp_entersub                        BEGIN
+ 0    -> Perl_pp_entersub                      import
+ 0    <- Perl_pp_leavesub                      import
+ 0  <- Perl_pp_leavesub                        BEGIN
+ 0  -> Perl_pp_entersub                        BEGIN
+ 0    -> Perl_pp_entersub                      dress
+ 0    <- Perl_pp_leavesub                      dress
+ 0    -> Perl_pp_entersub                      dirty
+ 0    <- Perl_pp_leavesub                      dirty
+ 0    -> Perl_pp_entersub                      whiten
+ 0    <- Perl_pp_leavesub                      whiten
+ 0  <- Perl_dounwind                           BEGIN
+
+=item Function calls during interpreter cleanup
+
+ # dtrace -Zn 'phase-change /copyinstr(arg0) == "END"/ { self->ending = 1 } sub-entry /self->ending/ { trace(copyinstr(arg0)) }'
+
+ CPU     ID                    FUNCTION:NAME
+   1  77214       Perl_pp_entersub:sub-entry   END
+   1  77214       Perl_pp_entersub:sub-entry   END
+   1  77214       Perl_pp_entersub:sub-entry   cleanup
+   1  77214       Perl_pp_entersub:sub-entry   _force_writable
+   1  77214       Perl_pp_entersub:sub-entry   _force_writable
+
+=item System calls at compile time
+
+ # 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) }'
+
+ lseek                                                           310
+ read                                                            374
+ stat64                                                         1056
+
+=item Perl functions that execute the most opcodes
+
+ # dtrace -qZn 'sub-entry { self->fqn = strjoin(copyinstr(arg3), strjoin("::", copyinstr(arg0))) } op-entry /self->fqn != ""/ { @[self->fqn] = count() } END { trunc(@, 3) }'
+
+ warnings::unimport                                             4589
+ Exporter::Heavy::_rebuild_cache                                5039
+ Exporter::import                                              14578
 
 =back
 
@@ -127,13 +208,24 @@ from a DTrace action.
 
 =over 4
 
-=item DTrace User Guide
+=item DTrace Dynamic Tracing Guide
 
-L<http://download.oracle.com/docs/cd/E19082-01/819-3620/index.html>
+L<http://dtrace.org/guide/preface.html>
 
 =item DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
 
-L<http://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/>
+L<https://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/>
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<Devel::DTrace::Provider>
+
+This CPAN module lets you create application-level DTrace probes written in
+Perl.
 
 =back