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

cpanm Class::ReluctantORM

perl -MCPAN -e shell
install Class::ReluctantORM