The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Class-ReluctantORM-0.52_0
River stage zero No dependents
++
/ Class::ReluctantORM::Monitor

NAME

Class::ReluctantORM::Monitor - Monitor CRO Driver activity

SYNOPSIS

  use aliased 'Class::ReluctantORM::Monitor::ColumnCount';
  # You can also make your own

  # Create a new monitor (args vary with monitor)
  my $mon = ColumnCount->new(log => $io, log_prefix => 'yipes', ...);

  # Install globally
  Class::ReluctantORM->install_global_monitor($mon);

  # Install only for the Ship class's driver
  Model::Ship->driver->install_monitor($mon);

  # Turn on Origin Tracking to find out where the query is being generated
  Class::ReluctantORM->enable_origin_tracking(1);

  # Make queries, etc...
  # Things get logged to $io

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.

Monitors may be global or class-specific. Global monitors are installed by calling Class::ReluctantORM->install_global_monitor($mon), and will affect all CRO interactions. Class-specific monitors are installed onto the class's driver, using TheClass->driver->install_monitor($mon), and will only monitor queries originating on that class.

Monitors are grouped into two broad categories: general monitors, which can do anything, and measuring monitors, which have special facilities for measuring, tracking, and acting on a value that they measure.

Several Monitors are included with Class::ReluctantORM (all have Class::ReluctantORM::Monitor as a prefix):

Dump

Dumps the query structures to the log.

QueryCount

Counts the number of statements executed. A Measuring monitor.

ColumnCount

Counts the number of columns returned by a query. A Measuring monitor.

JoinCount

Counts the number of JOINs in the query. A Measuring monitor.

QuerySize

Monitors the total size, in bytes, of the data returned by a query. A Measuring monitor.

RowCount

Monitors the number of rows returned by the query. A Measuring monitor.

RowSize

Monitors the size, in bytes, of each individual row. A Measuring monitor.

Timer

Tracks execution time of each query. A Measuring monitor.

CONTROLLING WHAT TO OUTPUT

These are the possible values for the 'what' option to new(), which controls what data gets logged.

sql_object - the abstract Class::ReluctantORM::SQL object, via Data::Dumper
sql_object_pretty - the abstract Class::ReluctantORM::SQL object, pretty-printed
statement - the rendered SQL statement as a string
binds - the list of bind arguments, given to execute()
row - the structure returned by fetchrow_hashref
origin - the line, file, and package where the query originated

CONSTRUCTORS

$mon = SomeMonitor->new(...);

Creates a new monitor. Monitors may extend the list of supported options, but all support:

log - an IO::Handle or the string 'STDOUT' or 'STDERR'

Append any log messages to this handle. If not present, logging is disabled.

log_prefix - optional string

Prefix to be used in log messages. Can be used to distinguish this monitor from others.

trace_limit - optional integer

If you use the 'origin' option to 'what', use this to specify how many frames to go back from the origin of the query. Default: no limit.

what - optional arrayref of strings, or the string 'all'.

When logging, indicates what values to log. Different monitors have different defaults for this. See CONTROLLING WHAT TO OUTPUT for more info.

when - optional arrayref of strings, or the string 'all'.

Indicates which events to pay attention to. Some monitors may constrain this value because they must listen at certain events. See CONTROLLING WHEN TO OUTPUT for more info.

Measuring monitors have additional options:

log_threshold - optional number

If the measured value is less than this, no log entry is made. Default: always log.

fatal_threshold - optional number

Reflects a hard limit. If the measured value exceeds the limit, an exception is thrown. Default: no exceptions.

highwater_count - integer

If present, enables a "scoreboard" effect. This many records will be kept (for example, the top 5 queries by column count). See Class::ReluctantORM::Monitor::Measure - highwater_marks(). Default: remember 5 records.

$bool = $mon->supports_measuring();

Returns true if the Monitor supports measuring something (a metric). Default implementation returns false.

MONITOR EVENT INTERFACE METHODS

These methods are called whenever a Driver event occurs.

The default implementation is a no-op.

All methods take named parameters. Each method lists its required arguments. The arguments are as follows:

driver

The Driver that is performing the work.

sql_obj

The Class::ReluctantORM::SQL object being rendered.

sql_str

The rendered SQL string, ready for a prepare(). This will be in the driver's dialect.

sth

The DBI statement handle.

binds

An arrayref of arguments to DBI execute().

row

A hashref of data returned by a single row, as returned by $sth->fetchrow_hashref

$d->notify_render_begin(sql_obj => $so);

Notifies the monitoring system that the driver has begun work to render the given SQL object.

Arguments: sql_obj, original, untouched Class::ReluctantORM::SQL object.

$d->notify_render_transform(sql_obj => $so);

Notifies the monitoring system that the driver has finished transforming the SQL object.

Arguments: sql_obj, the post-transformation Class::ReluctantORM::SQL object.

$d->notify_render_finish(sql_obj => $so, sql_str => $ss);

Notifies the monitoring system that the driver has finished rendering the SQL object.

$d->notify_execute_begin(sql_obj => $so, sql_str => $ss, sth =>$sth, binds => \@binds);

Notifies the monitoring system that the driver is about to perform a DBI execute.

$d->notify_execute_finish(sql_obj => $so, sql_str => $ss, sth =>$sth, binds => \@binds);

Notifies the monitoring system that the driver has returned from performing a DBI execute.

$d->notify_fetch_row(sql_obj => $so, sql_str => $ss, sth =>$sth, binds => \@binds, row => \%row);

Notifies the monitoring system that the driver has returned from performing a DBI fetchrow.

$d->notify_finish(sql_obj => $so, sql_str => $ss, sth => $sth);

Notifies the monitoring system that the driver has finished the query.