NAME
Devel::DTrace::Provider::Builder - declaratively create DTrace USDT providers
SYNOPSIS
package MyApp::DTraceProviders;
use strict;
use warnings;
use Devel::DTrace::Provider::Builder;
provider 'backend' => as {
probe 'process_start', 'integer';
probe 'process_end', 'integer';
};
provider 'frontend' => as {
probe 'render_start', 'string';
probe 'render_end', 'string';
};
# elsewhere
use MyApp::DTraceProviders;
process_startDESCRIPTION
This module provides a declarative way of creating DTrace providers, in packages which export their probes on import. This is typically what you want when creating a provider for use in a large application:
- Declare your provider in its own package
- Use the provider in your application
- Fire the probes imported
Declare the providers
You can declare any number of providers in a single package: they will all be enabled and their probes imported when the package is used.
The general syntax of a provider declaration is:
provider 'provider_name' => as {
probe 'probe_name', [ 'argument-type', ... ];
...
};The supported argument types are 'integer' and 'string', corresponding to native int and char * probe arguments.
Use the provider
Just use the package where you defined the provider:
use MyApp::DTraceProviders;This will import all the probe subs defined in the package into your namespace.
Fire the probes
To fire a probe, call the function, passing a coderef in which you call the fire method on $_[0]:
probe { shift->fire };The coderef is only called if the probe is enabled by DTrace, so you can do whatever work is necessary to gather probe arguments and know that code will not run when DTrace is not active:
probe {
my @args = gather_expensive_args();
shift->fire(@args);
}; DISABLED PROBE EFFECT
Two features allow you to reduce the disabled probe effect:
Argument-gathering coderef
This applies to code on DTrace enabled systems: the coderef is only executed if the probe is enabled, so you can put code there which only runs when tracing is active.
*_enabled functions
This applies to systems without DTrace: if you form your probe tracepoints with a postfix if, like this:
fooprobe { shift->fire } if fooprobe_enabled();on a system without DTrace, fooprobe_enabled will be a constant sub returning 0, and the entire line will be optimised away, which means probes embedded in code have zero overhead. This feature is taken from Tim Bunce's DashProfiler:
http://search.cpan.org/~timb/DashProfiler-1.13/lib/DashProfiler/Import.pm
CAVEATS
This code only works on Mac OS X 10.5 "Leopard" and Solaris 10U1 and later (including OpenSolaris, SXCE, etc), running on i386 or x86_64 with a 32 bit perl. SPARC and PowerPC are currently unsupported.