{ "mode": "man", "parameter": "perldtrace", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/perldtrace/1/json", "generated": "2026-06-14T13:02:08Z", "synopsis": "# dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'\ndtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes\n# perl -E 'sub outer { inner(@) } sub inner { say shift } outer(\"hello\")'\nhello\n(dtrace output)\nCPU ID FUNCTION:NAME\n0 75915 Perlppentersub:sub-entry BEGIN\n0 75915 Perlppentersub:sub-entry import\n0 75922 Perlppleavesub:sub-return import\n0 75922 Perlppleavesub:sub-return BEGIN\n0 75915 Perlppentersub:sub-entry outer\n0 75915 Perlppentersub:sub-entry inner\n0 75922 Perlppleavesub:sub-return inner\n0 75922 Perlppleavesub:sub-return outer", "sections": { "NAME": { "content": "perldtrace - Perl's support for DTrace\n", "subsections": [] }, "SYNOPSIS": { "content": "# dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'\ndtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes\n\n# perl -E 'sub outer { inner(@) } sub inner { say shift } outer(\"hello\")'\nhello\n\n(dtrace output)\nCPU ID FUNCTION:NAME\n0 75915 Perlppentersub:sub-entry BEGIN\n0 75915 Perlppentersub:sub-entry import\n0 75922 Perlppleavesub:sub-return import\n0 75922 Perlppleavesub:sub-return BEGIN\n0 75915 Perlppentersub:sub-entry outer\n0 75915 Perlppentersub:sub-entry inner\n0 75922 Perlppleavesub:sub-return inner\n0 75922 Perlppleavesub:sub-return outer\n", "subsections": [] }, "DESCRIPTION": { "content": "DTrace is a framework for comprehensive system- and application-level tracing. Perl is a\nDTrace provider, meaning it exposes several probes for instrumentation. You can use these in\nconjunction with kernel-level probes, as well as probes from other providers such as MySQL,\nin order to diagnose software defects, or even just your application's bottlenecks.\n\nPerl must be compiled with the \"-Dusedtrace\" option in order to make use of the provided\nprobes. While DTrace aims to have no overhead when its instrumentation is not active, Perl's\nsupport itself cannot uphold that guarantee, so it is built without DTrace probes under most\nsystems. One notable exception is that Mac OS X ships a /usr/bin/perl with DTrace support\nenabled.\n", "subsections": [] }, "HISTORY": { "content": "5.10.1\nPerl's initial DTrace support was added, providing \"sub-entry\" and \"sub-return\" probes.\n\n5.14.0\nThe \"sub-entry\" and \"sub-return\" probes gain a fourth argument: the package name of the\nfunction.\n\n5.16.0\nThe \"phase-change\" probe was added.\n\n5.18.0\nThe \"op-entry\", \"loading-file\", and \"loaded-file\" probes were added.\n", "subsections": [] }, "PROBES": { "content": "sub-entry(SUBNAME, FILE, LINE, PACKAGE)\nTraces the entry of any subroutine. Note that all of the variables refer to the\nsubroutine that is being invoked; there is currently no way to get ahold of any\ninformation about the subroutine's caller from a DTrace action.\n\n:*perl*::sub-entry {\nprintf(\"%s::%s entered at %s line %d\\n\",\ncopyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);\n}\n\nsub-return(SUBNAME, FILE, LINE, PACKAGE)\nTraces the exit of any subroutine. Note that all of the variables refer to the subroutine\nthat is returning; there is currently no way to get ahold of any information about the\nsubroutine's caller from a DTrace action.\n\n:*perl*::sub-return {\nprintf(\"%s::%s returned at %s line %d\\n\",\ncopyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);\n}\n\nphase-change(NEWPHASE, OLDPHASE)\nTraces changes to Perl's interpreter state. You can internalize this as tracing changes\nto Perl's \"${^GLOBALPHASE}\" variable, especially since the values for \"NEWPHASE\" and\n\"OLDPHASE\" are the strings that \"${^GLOBALPHASE}\" reports.\n\n:*perl*::phase-change {\nprintf(\"Phase changed from %s to %s\\n\",\ncopyinstr(arg1), copyinstr(arg0));\n}\n\nop-entry(OPNAME)\nTraces the execution of each opcode in the Perl runloop. This probe is fired before the\nopcode is executed. When the Perl debugger is enabled, the DTrace probe is fired after\nthe debugger hooks (but still before the opcode itself is executed).\n\n:*perl*::op-entry {\nprintf(\"About to execute opcode %s\\n\", copyinstr(arg0));\n}\n\nloading-file(FILENAME)\nFires when Perl is about to load an individual file, whether from \"use\", \"require\", or\n\"do\". This probe fires before the file is read from disk. The filename argument is\nconverted to local filesystem paths instead of providing \"Module::Name\"-style names.\n\n:*perl*:loading-file {\nprintf(\"About to load %s\\n\", copyinstr(arg0));\n}\n\nloaded-file(FILENAME)\nFires when Perl has successfully loaded an individual file, whether from \"use\",\n\"require\", or \"do\". This probe fires after the file is read from disk and its contents\nevaluated. The filename argument is converted to local filesystem paths instead of\nproviding \"Module::Name\"-style names.\n\n:*perl*:loaded-file {\nprintf(\"Successfully loaded %s\\n\", copyinstr(arg0));\n}\n", "subsections": [] }, "EXAMPLES": { "content": "Most frequently called functions\n# dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),\"::\"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'\n\nClass::MOP::Attribute::slots 400\nTry::Tiny::catch 411\nTry::Tiny::try 411\nClass::MOP::Instance::inlineslotaccess 451\nClass::MOP::Class::Immutable::Trait:::around 472\nClass::MOP::Mixin::AttributeCore::hasinitializer 496\nClass::MOP::Method::Wrapped::ANON 544\nClass::MOP::Package::packagestash 737\nClass::MOP::Class::initialize 1128\nClass::MOP::getmetaclassbyname 1204\n\nTrace function calls\n# dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'\n\n0 -> Perlppentersub BEGIN\n0 <- Perlppleavesub BEGIN\n0 -> Perlppentersub BEGIN\n0 -> Perlppentersub import\n0 <- Perlppleavesub import\n0 <- Perlppleavesub BEGIN\n0 -> Perlppentersub BEGIN\n0 -> Perlppentersub dress\n0 <- Perlppleavesub dress\n0 -> Perlppentersub dirty\n0 <- Perlppleavesub dirty\n0 -> Perlppentersub whiten\n0 <- Perlppleavesub whiten\n0 <- Perldounwind BEGIN\n\nFunction calls during interpreter cleanup\n# dtrace -Zn 'phase-change /copyinstr(arg0) == \"END\"/ { self->ending = 1 } sub-entry /self->ending/ { trace(copyinstr(arg0)) }'\n\nCPU ID FUNCTION:NAME\n1 77214 Perlppentersub:sub-entry END\n1 77214 Perlppentersub:sub-entry END\n1 77214 Perlppentersub:sub-entry cleanup\n1 77214 Perlppentersub:sub-entry forcewritable\n1 77214 Perlppentersub:sub-entry forcewritable\n\nSystem calls at compile time\n# 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) }'\n\nlseek 310\nread 374\nstat64 1056\n\nPerl functions that execute the most opcodes\n# dtrace -qZn 'sub-entry { self->fqn = strjoin(copyinstr(arg3), strjoin(\"::\", copyinstr(arg0))) } op-entry /self->fqn != \"\"/ { @[self->fqn] = count() } END { trunc(@, 3) }'\n\nwarnings::unimport 4589\nExporter::Heavy::rebuildcache 5039\nExporter::import 14578\n", "subsections": [] }, "REFERENCES": { "content": "DTrace Dynamic Tracing Guide\n\n\nDTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD\n\n", "subsections": [] }, "SEE ALSO": { "content": "Devel::DTrace::Provider\nThis CPAN module lets you create application-level DTrace probes written in Perl.\n", "subsections": [] }, "AUTHORS": { "content": "Shawn M Moore \"sartak@gmail.com\"\n\n\n\nperl v5.34.0 2025-07-25 PERLDTRACE(1)", "subsections": [] } }, "summary": "perldtrace - Perl's support for DTrace", "flags": [], "examples": [ "Most frequently called functions", "# 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::inlineslotaccess 451", "Class::MOP::Class::Immutable::Trait:::around 472", "Class::MOP::Mixin::AttributeCore::hasinitializer 496", "Class::MOP::Method::Wrapped::ANON 544", "Class::MOP::Package::packagestash 737", "Class::MOP::Class::initialize 1128", "Class::MOP::getmetaclassbyname 1204", "Trace function calls", "# dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'", "0 -> Perlppentersub BEGIN", "0 <- Perlppleavesub BEGIN", "0 -> Perlppentersub BEGIN", "0 -> Perlppentersub import", "0 <- Perlppleavesub import", "0 <- Perlppleavesub BEGIN", "0 -> Perlppentersub BEGIN", "0 -> Perlppentersub dress", "0 <- Perlppleavesub dress", "0 -> Perlppentersub dirty", "0 <- Perlppleavesub dirty", "0 -> Perlppentersub whiten", "0 <- Perlppleavesub whiten", "0 <- Perldounwind BEGIN", "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 Perlppentersub:sub-entry END", "1 77214 Perlppentersub:sub-entry END", "1 77214 Perlppentersub:sub-entry cleanup", "1 77214 Perlppentersub:sub-entry forcewritable", "1 77214 Perlppentersub:sub-entry forcewritable", "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", "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::rebuildcache 5039", "Exporter::import 14578" ], "see_also": [] }