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

DashProfiler documentation Contained in the DashProfiler distribution.

Index

Code Index:

NAME

Top

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

SYNOPSIS

Top

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

Top

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

Top

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

Top

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

Top

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

Top

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

COPYRIGHT

Top

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.

DashProfiler documentation Contained in the DashProfiler distribution. 
package DashProfiler;

use strict;
use warnings;

our $VERSION = "1.13"; # $Revision: 48 $


use Carp;
use Data::Dumper;

use DashProfiler::Core;

my %profiles;
my %precondition;


sub add_profile {
    my $class = shift;
    croak "A profile called '$_[0]' already exists" if $profiles{$_[0]};
    my $self = DashProfiler::Core->new(@_);
    $profiles{ $self->{profile_name} } = $self;
    return $self;
}



sub prepare {
    my $class = shift;
    my $profile_name = shift;
    my $profile_ref = $profiles{$profile_name};
    unless ($profile_ref) { # to catch spelling mistakes
        carp "No $class profiler called '$profile_name' exists"
            unless defined $profile_ref;
        $profiles{$profile_name} = 0; # only warn once
        return;
    };
    return $profile_ref->prepare(@_);
}



sub profile_names {
    my $class = shift;
    # return keys but skip 0 entries that might be added by prepare()
    return grep { $profiles{$_} } keys %profiles;
}



sub get_profile {
    my ($self, $profile_name) = @_;
    return $profiles{$profile_name};
}



sub profile_as_text {
    my $self = shift;
    my $profile_name = shift;
    my $profile_ref = $self->get_profile($profile_name) or return;
    return $profile_ref->profile_as_text(@_);
}



sub all_profiles_as_text {
    my $class = shift;
    return map { $profiles{$_}->profile_as_text() } sort keys %profiles;
}



sub dump_all_profiles {
    my $class = shift;
    warn $_ for $class->all_profiles_as_text();
    return 1;
}



sub reset_all_profiles {    # eg PerlChildInitHandler
    my $class = shift;
    if (my $pre = $precondition{reset_all_profiles}) {
	return 1 unless $pre->();
    }
    $_->reset_profile_data for values %profiles;
    return -1; # DECLINED
}
$precondition{reset_all_profiles} = undef;



sub flush_all_profiles {    # eg PerlChildExitHandler
    my $class = shift;
    if (my $pre = $precondition{flush_all_profiles}) {
	return -1   # DECLINED
            unless $pre->();
    }
    $_->flush for values %profiles;
    return -1;  # DECLINED
}
$precondition{flush_all_profiles} = undef;



sub start_sample_period_all_profiles { # eg PerlPostReadRequestHandler
    my $class = shift;
    if (my $pre = $precondition{start_sample_period_all_profiles}) {
	return -1   # DECLINED
            unless $pre->();
    }
    $_->start_sample_period for values %profiles;
    return -1;   # DECLINED
}
$precondition{start_sample_period_all_profiles} = undef;



sub end_sample_period_all_profiles { # eg PerlCleanupHandler
    my $class = shift;
    if (my $pre = $precondition{end_sample_period_all_profiles}) {
	return -1   # DECLINED
            unless $pre->();
    }
    $_->end_sample_period for values %profiles;
    $_->flush_if_due      for values %profiles;
    return -1;  # DECLINED
}
$precondition{end_sample_period_all_profiles} = undef;


sub set_precondition {
    my ($class, $name, $code) = @_;
    croak "Not a CODE reference" if $code and ref $code ne 'CODE';
    croak "Invalid function name '$name'" unless exists $precondition{$name};
    $precondition{$name} = $code;
    return;
}



1;