NAME

DashProfiler - efficiently collect call count and timing data aggregated by context

SYNOPSIS

The DashProfiler modules enable you to efficiently collect performance data by adding just a line of code to the functions or objects you want to monitor.

Data is aggregated by context and optionally also by a granular time axis.

See DashProfiler::UserGuide for a general introduction.

DESCRIPTION

Performance

DashProfiler is fast, very fast. Especially given the functionality and flexibility it offers.

When you build DashProfiler, the test suite shows the performance on your system when you run "make test". On my system, for example it reports:

t/02.sample.......ok 1/0 you're using perl 5.010000 on darwin-2level -O3     
  Average 'cold' sample overhead is 0.000021s (max 0.000104s, min 0.000019s)
  Average 'hot'  sample overhead is 0.000017s (max 0.000102s, min 0.000016s)

Apache mod_perl

DashProfiler was designed to work well with Apache mod_perl in high volume production environments.

Refer to DashProfiler::Apache for details.

PRIMARY METHODS

add_profile

DashProfiler->add_profile( 'my_profile_name' );
DashProfiler->add_profile( my_profile_name => { ... } );
$core = DashProfiler->add_core( my_profile_name => { ... } );

Calls DashProfiler::Core->new to create a new DashProfiler::Core object and then caches it, using the name as the key, so it can be refered to by name.

See DashProfiler::Core for details of the arguments.

prepare

$sampler = DashProfiler->prepare($profile_name, ...);

Calls prepare(...) on the DashProfiler named by $profile_name. Returns a sampler code reference prepared to take samples.

If no profile with that name exists then it will warn, but only once per name.

profile_names

@profile_names = DashProfiler->profile_names;

Returns a list of all the profile names added via "add_profile".

get_profile

$core = DashProfiler->get_profile( $profile_name );

Returns the DashProfiler::Core object associated with that name.

profile_as_text

$text = DashProfiler->profile_as_text( $profile_name )

Calls profile_as_text(...) on the DashProfiler named by $profile_name. Returns undef if no profile with that name exists.

METHODS AFFECTING ALL PROFILES

all_profiles_as_text

@text = DashProfiler->all_profiles_as_text

Calls profile_as_text() on all profiles, ordered by name.

dump_all_profiles

dump_all_profiles()

Equivalent to

warn $_ for DashProfiler->all_profiles_as_text();

reset_all_profiles

Calls reset_profile_data for all profiles.

Typically called from mod_perl PerlChildInitHandler.

flush_all_profiles

flush_all_profiles()

Calls flush() for all profiles. Typically called from mod_perl PerlChildExitHandler

start_sample_period_all_profiles

start_sample_period_all_profiles()

Calls start_sample_period() for all profiles. Typically called from mod_perl PerlPostReadRequestHandler

end_sample_period_all_profiles

end_sample_period_all_profiles()

Calls end_sample_period() for all profiles. Then calls flush_if_due() for all profiles. Typically called from mod_perl PerlCleanupHandler

OTHER METHODS

set_precondition

DashProfiler->set_precondition( function => sub { ... } );

Available functions are:

reset_all_profiles
flush_all_profiles
start_sample_period_all_profiles
end_sample_period_all_profiles

The set_precondition method associates a code reference with a function. When the function is called the corresponding precondition code is executed first. If the precondition code does not return true then the function returns immediately.

This mechanism is most useful for fine-tuning when periods start and end. For example, there may be times when start_sample_period_all_profiles() is being called when you might not want to actually start a new period.

Alternatively the precondition code could itself call start_sample_period() for one or more specific profiles and then return false.

See DashProfiler::Apache for an example use.

AUTHOR

DashProfiler by Tim Bunce, http://www.tim.bunce.name and http://blog.timbunce.org

COPYRIGHT

The DashProfiler distribution is Copyright (c) 2007-2008 Tim Bunce. Ireland. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.