/ 
OpenInteract-1.99_06
River stage zero No dependents
/ OpenInteract2::ErrorStorage

NAME

OpenInteract2::ErrorStorage - Serialize serious errors to the filesystem

SYNOPSIS

# Default usage - get path from available context
my $storage = OpenInteract2::ErrorStorage->new();

# ...you can also specify the error directory
my $storage = OpenInteract2::ErrorStorage->new( '/path/to/errors' );

# Store an error
my $file = $storage->save( \%error_info );
_
# Get error distribution by day for the current month...
my %breakdown = $storage->get_breakdown_by_day();

# ...for a specific month in the same year
my %breakdown = $storage->get_breakdown_by_day( month => 2 );

# ...for a specific month
my %breakdown = $storage->get_breakdown_by_day( month => 2, year => 2005 );

# Get error distributions by month over a span of 6 months
# from the current month:
my %breakdown = $storage->get_breakdown_by_month();

# Get error distributions by month over a span of 3 months from a
# specific month (will give you 1-2005, 2-2005, 3-2005)
my %breakdown = $storage->get_breakdown_by_month(
    year => 2005, month => 1, months => 3
);

# Get most recent 5 errors from the last 30 days (defaults)
my @errors = $storage->get_most_recent();

# Get most recent 10 errors from the last 30 days
my @errors = $storage->get_most_recent( 10 );

# Get most recent 10 errors but only in the last 2 days
my @errors = $storage->get_most_recent( 10, 2 );

# Get all errors from today
my @errors = $storage->get_by_date();

# ...from yesterday and today
my @errors = $storage->get_by_date( days => 2 );

# ...from a particular day
my @errors = $storage->get_by_date( date => '2005-04-01' );

# ...from a particular day and the following 6 days
my @errors = $storage->get_by_date( date => '2005-04-01', days => 7 );

# Each member is an OpenInteract2::Error object...
foreach my $error ( @errors ) {
    print "Error time: ", $error->time->strftime( '%Y-%m-%d %H:%M' );
    ...
}

# Remove errors for a particular day
my @deleted_files = $storage->remove_by_date( '2005-02-28' );

# Same thing...
my @deleted_files = $storage->remove_by_date( '2005-02-28', 1 );

# Remove errors for a date range -- in this case, for 2005-02-28 and
# the following six days
my @deleted_files = $storage->remove_by_date( '2005-02-28', 7 );

DESCRIPTION

This class is responsible for storing, retrieving and removing errors from the filesystem. These errors are typically generated by calls to Log::Log4perl at an ERROR level or higher, but the actual level is configurable in your logging configuration.

The data stored on disk are very simple and human-readable. The base_error package also contains actions for browsing the errors and clearing out old errors.

The directory structure for storing errors is hashed by date. So instead of everything in one directory you'll have:

error_dir/2005-05/01/*.txt
error_dir/2005-05/02/*.txt
error_dir/2005-06/01/*.txt
error_dir/2005-06/02/*.txt

The files stored in each day's directory are timestamped (easy to order). So you might have:

error_dir/2005-05/01/041532-451.txt # 4:15 AM, 32 seconds, 451 milliseconds
error_dir/2005-05/01/212001-991.txt # 9:12 PM, 1 second, 991 milliseconds
...

The data stored in each file is in a human-readable but easily parseable format (no XML, INI or Perl).

CLASS METHODS

new( [ $error_dir ] )

Create a new storage object. If $error_dir not specified we pull the information from the available OpenInteract2::Context object.

OBJECT METHODS

NOTE: Wherever $date is specified we take it in the format '%Y-%m-%d', or '2005-05-01' for May 1, 2005. If you give us a date in the wrong format we throw an exception.

NOTE: All errors returned from this method have their id attribute set to a unique identifier derived from the date. It matches the pattern:

%Y-%m %d %H%M%S-%3N

You'll notice that this conveniently matches the pattern we use to store the errors:

%Y-%m/%d/%H%M%S-%3N.txt

save( \%error_info )

Create a OpenInteract2::Error object with \%error_info and store it to disk. Keys in \%error_info match up with the properties in OpenInteract2::Error.

Returns: filename where object stored.

get_most_recent( [ $num_errors ], [ $max_days ] )

Retrieve most recent errors. With no arguments it returns the most recent 5 errors from the last 30 days.

Parameters are:

num_errors (int; optional -- defaults to 5)

Number of errors to retrieve.

max_days (int; optional -- defaults to 30)

Maximum number of days to look back to satisfy num_errors.

Example:

# Get most recent 20 errors from the last 30 days
my @errors = $storage->get_most_recent( 20 );

# Get most recent 20 errors, but only from the last week; if 20
# errors not stored in the last week @errors will be smaller than 20
my @errors = $storage->get_most_recent( 20, 7 );

get_by_date( [ %date_info ] )

Retrieve list of errors by date. With no arguments it returns all errors from today.

Parameters are:

date (yyyy-mm-dd; optional -- defaults to today)

Date, or with days the starting date, for which I should retrieve errors.

days (int; optional -- defaults to 1)

Number of days, inclusive, starting with date, for which I should retrieve errors.

date_id (yyyy-mm dd HHMMSS-NNN; optional)

Pattern by which we can retrieve a particular date. The return list will have only one element if the error with this date is found, zero if no.t

Example:

# Get all errors from May 1, 2005
my @errors = $storage->get_by_date( '2005-05-01' );

# Get all errors from May 1, 2, and 3 in 2005
my @errors = $storage->get_by_date( '2005-05-01', 3 );

get_breakdown_by_month( %date_info )

Returns a hash of errors in storage indexed by month. The keys of the hash are formatted 'yyyy-mm', or '2005-02' for 'February, 2005' and the value for each key is a count of errors in that month.

Parameters:

year (optional; defaults to current year)
month (optional; defaults to current month)
months (optional; defaults to 6)

Number of months for which you want a breakdown -- it's an implied negative number since the year/month specify the latest date for which you want a report.

Example:

# Current month - 6
my %bd = $storage->get_breakdown_by_month();

# Jan 2005, Dec 2004, Nov 2004
my %bd = $storage->get_breakdown_by_month(
    year => 2005, month => 1, months => 3
);

get_breakdown_by_day( %date_info )

Returns a hash of errors in storage in a particular month indexed by day. The keys of the hash are formatted 'dd', or '09' for the ninth day of the month. Each key is a count of errors for that day.

Parameters:

year (optional; defaults to current year)
month (optional; defaults to current month)

Example:

# Get error counts for days in the current month:
my %bd = $self->get_breakdown_by_day();

# Get error counts for days in Feb 2005:
my %bd = $self->get_breakdown_by_day( year => 2005, month => 2 );

remove_by_date( $date, [ $days ] )

Removes multiple error files by date. Returns a list of files deleted.

Parameters are:

date (yyyy-mm-dd; required)

Date, or with days the starting date, for which I should remove the files.

days (int; optional -- defaults to 1)

Number of days, inclusive, starting with date, for which I should remove the files.

Example:

# Remove all errors from May 1, 2005
$storage->remove_by_date( '2005-05-01' );

# Remove all errors from May 1, 2, and 3 in 2005
$storage->remove_by_date( '2005-05-01', 3 );

SEE ALSO

OpenInteract2::Error

OpenInteract2::Log::OIAppender

COPYRIGHT

Copyright (c) 2005 Chris Winters. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHORS

Chris Winters <chris@cwinters.com>