NAME
Class::ReluctantORM::Monitor::Measuring - Monitor with Metric support
SYNOPSIS
#####
# Using a Measuring Monitor
#####
# Interrogate the monitor
print "Last query had " . $mon->last_measured_value() . " foo units\n";
# Worst offenders overall
foreach my $info ($mon->highwater_marks()) {
print "Rank: " . $info->{rank} . "\n";
print "Foo Count: " . $info->{measured_value} . "\n";
print "Query Object: " . $info->{sql}->pretty_print() . "\n";
# next three depend on Origin Tracking being enabled
print "Origin File: " . $info->{origin}->{file} . "\n";
print "Origin Line: " . $info->{origin}->{line} . "\n";
print "Origin Package: " . $info->{origin}->{package} . "\n";
}
# Can also log, etc - does everything a regular Monitor can do
#####
# Creating a new Measuring Monitor
#####
package FooCount;
use base 'Class::ReluctantORM::Monitor::Measuring';
sub measurement_label { return 'Foo Count (Instantaneous)'; }
sub default_events { return @list_of_when; }
sub permitted_events { return @list_of_when; }
# Gets called whenever a measurement needs to be taken
sub take_measurement {
my %event_info = @_; # sql_obj, binds, etc
return $foo_count;
}DESCRIPTION
The Monitor facility allows you to peek inside the Class::ReluctantORM SQL render, execute, and fetch process, and see what is going on. Several monitors are included with Class::ReluctantORM, and it is easy to write your own.
The Measuring Monitors have special support to obtain, track, and act on a measured value.
See Class::ReluctantORM::Monitor for info about using MOnitors in general. This file only documents the measuring extensions.
CONSTRUCTORS
$mon = SomeMonitor->new(...);
See Class::ReluctantORM::Monitor::new().
MEASURING API
These methods should be overridden to implement your monitor's behavior.
$str = $mon->measurement_label();
Returns a string to be included in the log to label the measured value. Default is "$monitor_class Observation".
@whens = $mon->permitted_events();
Returns a list of events for which it is permitted to take a measurement for this monitor. If you instantiate a monitor, and request an event not on this list, an exception will be thrown.
Default is all events permitted.
@whens = $mon->default_events();
Returns a list of events at which measurmeents will automatically be taken, if you do not override this with the 'when' option to new().
Default is all events.
$number = $mon->take_measurement(%event_info);
Pure virtual - your Monitor subclass must implement this method.
Called when the monitor needs to take a measurement. The arguments will be a hash of the event arguments (See Class::ReluctantORM::Monitor - Monitor Interface Methods section), with an additional 'event' key whose value is the name of the event.
HIGHWATER TRACKING
Measuring-style Monitors may also support Highwater Tracking. As the Monitor makes observations, it maintains a list of the N worst unique observations. N is determined by the value of the highwater_count option passed to the monitor constructor. Observations are considered the same if they have the same count and same origin.
@observations = $mon->highwater_marks()
Returns an array of hashes describing the N unique observations whose measured_value was the largest.
Each hashref has the following keys:
- rank
-
Current rank in the highwater scoreboard, with 1 the worst.
- measured_value
-
The observed value.
- sql
-
The SQL object being executed at the time.
- origin
-
Present only if Origin Tracking is enabled (see Class::ReluctantORM->enable_origin_tracking()). If present, is a hash containing keys file, line, and package, indicating the location of the last stack frame outside of Class::ReluctantORM (usually "your" code).
$bool = $mon->supports_measuring();
Returns true if the Monitor supports counting something (a metric). This implementation returns true.
MONITOR INFORMATION INTERFACE METHODS
These methods provide information about the monitor.
$number = $mon->last_measured_value();
Returns the value of the last observation.
$mon->reset();
For measuring monitors, resets the last measured value to zero.
AUTHOR
Clinton Wolfe January 2011