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:
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::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>