NAME

BuzzSaw::Report - A Moose class which is used for generating BuzzSaw reports

VERSION

This documentation refers to BuzzSaw::Report version 0.12.0

SYNOPSIS

use BuzzSaw::Report;

my $report = BuzzSaw::Report->new( email_to => 'fred@example.org', template => 'myreport.tt', tags => 'kernel', start => 'yesterday', end => 'today', );

$report->generate();

DESCRIPTION

This module provides the functionality to search the BuzzSaw database for log events of interest and generate reports based on the results. In simple situations it can be used directly, for more complex searches or post-processing it can be sub-classed to allow the overriding of specific methods.

The BuzzSaw project provides a suite of tools for processing log file entries. Entries in files are parsed and filtered into a set of events of interest which are stored in a database. A report generation framework is also available which makes it easy to generate regular reports regarding the events discovered.

ATTRIBUTES

db

This is a reference to the BuzzSaw::DB object which will be used to find any events of interest.

It is possible to specify this as a string in which case that will be considered to be a configuration file name and it will be handed off to the new_with_config method for the BuzzSaw::DB class.

If you do not specify the BuzzSaw::DB object then a new one will be created by calling the new_with_config method (which will use the default configuration file name for that class).

name

This is the identifier for the report. The primary purpose of this attribute is for use by the BuzzSaw::Reporter module to track which reports have been completed. The default is to use the final part of the Perl module name (e.g. for BuzzSaw::Report::Kernel the default name is Kernel). You are only likely to need to set this if you are using the same Perl module to generate multiple different reports.

email_to

This attribute is used to hold the list of email addresses to which the report should be delivered. If the list is empty then the report will be printed to stdout instead. This attribute can be specified as a simple string (which may contain multiple comma-separated addresses) in which case it will be parsed and coerced into an array of separate addresses. All email addresses specified MUST be valid according to Email::Valid.

email_from

This is a string attribute is used to set the email address from which the report should be sent. If it is not set then the default chosen will depend on the configuration of your system. If an email address is specified it MUST be valid according to Email::Valid.

email_subject

This is a string attribute which is used to set the subject when sending the report by email. If it is not specified then the default will be BuzzSaw Report - concatenated with the name of the report.

template

This string attribute is the name of the template to be used to generate the report. The Perl Template Toolkit is used to process the files. Note that the file MUST exist within one of the directories specified in the tmpldirs attribute. If no file is specified then the default is based on the lower-cased value of the name attribute with a .tt suffix appended.

tmpldirs

This list attribute is used to control the set of directories which are searched for template files by the Template Toolkit. The default list contains /usr/share/buzzsaw/templates/reports and /usr/share/buzzsaw/templates.

start

This attribute is used to specify the start of the date/time range within which to search for events of interest. It holds a BuzzSaw::DateTime object. It can be specified as a simple string in which case it will be coerced into a new object. Supported strings include: now, today, recent, yesterday, this-week, this-month, this-year, week-ago, seconds from the unix epoch or variously formatted date/time strings. See the module documentation for full details.

end

This attribute is used to specify the end of the date/time range within which to search for events of interest. It holds a BuzzSaw::DateTime object. It can be specified as a simple string in which case it will be coerced into a new object. Supported strings include: now, today, recent, yesterday, this-week, this-month, this-year, week-ago, seconds from the unix epoch or variously formatted date/time strings. See the module documentation for full details.

timezone

This attribute is used to specify the timezone into which the event timestamps (the logtime field) should be converted. The default is local which relies on the DateTime module working out what is most suitable for your current time zone. All timestamps are stored in the database in UTC, if you do not want any conversion then set this attribute to UTC. This attribute actually takes a DateTime::TimeZone object but a string will be converted appropriately.

order_by

This attribute is used to control the order of the results from the search for events of interest. It can be either a reference to an array or a reference to a hash. For example:

order_by => [qw/hostname logtime/]

For explicit descending order:

 order_by => { -desc => [qw/col1 col2 col3/] }

For explicit ascending order:

 order_by => { -asc => 'col' }

program

This is the name of the program field you wish to match in the log messages. By default the value is the lower-cased version of the name attribute for the report module instance (e.g. for BuzzSaw::Report::Kernel it is kernel. If you wish to match all log messages then set this to the empty string ''.

tags

This list attribute is used to specify which tags to search for in the database when finding events of interest. If no tags are specified then the search will return all events found within the specified date/time range. The default is an empty list.

SUBROUTINES/METHODS

generate

@events = $report->find_events()

This method is used to construct the SQL query based on the date/time range and the tags specified (if any). In a sub-class this method can be overridden to do whatever is required to generate complex queries. It must return an array of events (i.e. the result from calling the DBIx::Class::ResultSet search method in a list context).

%results = $report->process_events(@events)

This method is used to do any post-processing of the events list which is more easily done in Perl rather than within the database itself. By default the method does nothing, override this in a sub-class if you need to do complex classification of events. It must return a hash which holds the results.

$text = $report->process_template( \%results, \@events )

This method uses the Perl Template Toolkit to generate the report text. It is passed a reference to the hash of results from the process_events method and a reference to the original list of events returned by the find_events method.

The references to the results hash and events list are passed into the template. Further to this a reference is passed in to a params hash which provides easy access to the values of the start, end and tags attributes.

The method returns the generated output as a simple text string.

send_email

If any email addresses have been specified via the email_to attribute then this method will be called to deliver the output via email. The first address in the email_to address will be set as the To field and any further addresses will be placed in the Cc field. The message is constructed and sent using the MIME::Lite module.

add_tmpldir

This can be used to add another directory to the list of those which will be searched for templates when generating the report. Note that the new directory is put onto the front of the list. This makes it possible to override any standard template provided in the default directories.

DEPENDENCIES

This module is powered by Moose and also uses MooseX::Types and MooseX::Types::EmailAddress. It uses the Perl Template Toolkit to generate the reports. It uses MIME::Lite to send reports via email.

SEE ALSO

BuzzSaw, BuzzSaw::Report::Kernel, BuzzSaw::DB, BuzzSaw::DateTime, BuzzSaw::Types.

PLATFORMS

This is the list of platforms on which we have tested this software. We expect this software to work on any Unix-like platform which is supported by Perl.

ScientificLinux6

BUGS AND LIMITATIONS

Please report any bugs or problems (or praise!) to bugs@lcfg.org, feedback and patches are also always very welcome.

AUTHOR

Stephen Quinney <squinney@inf.ed.ac.uk>

LICENSE AND COPYRIGHT

Copyright (C) 2012 University of Edinburgh. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the terms of the GPL, version 2 or later.