NAME

BuzzSaw::DB - The BuzzSaw database interface

VERSION

This documentation refers to BuzzSaw::DB version 0.12.0

SYNOPSIS

   use BuzzSaw::DB;

   my $db = BuzzSaw::DB->new( name => "logdb",
                              user => "fred",
                              pass => "letmein" );

   # or use a configuration file:

   my $db = BuzzSaw::DB->new_with_config();

   # Get the DBIx::Class schema:

   my $schema = $db->schema;

DESCRIPTION

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

configfile

This is the name of the configuration file which contains the settings for the other attributes for the object. This only has an effect when a new object is created using the new_with_config method. A number of file formats are supported (e.g. XML, YAML, JSON, Apache-style, Windows INI), see the Config::Any documentation for full details. The default value is /etc/buzzsaw/db.yaml which is a YAML format file.

name

This is the name of the database. This attribute MUST be specified, the default value is buzzsaw.

host

This is the host name for the database server. There is no default value, this attribute is optional.

port

This is the number of the port on which the database server is listening. There is no default value, this attribute is optional.

user

This is the name of the user to be used for accessing the database. There is no default value, this attribute is optional.

pass

This is the password for the user to be used for accessing the database. There is no default value, this attribute is optional.

schema

This gives access to the DBIx::Class::Schema object.

SUBROUTINES/METHODS

This class has the following methods:

new()

Create a new instance of this class. Optionally a hash (or reference to a hash) of attributes and their values can be specified.

new_with_config

Create a new instance of this class using the attribute values set in a configuration file. By default, the /etc/buzzsaw/db.yaml will be loaded, if it exists. The configuration file can be changed by passing in a value for the configfile attribute.

start_processing( $logname, $digest, $readall )

This method takes the name of the log and the computed SHA digest for the file and attempts to register the start of processing into the currentprocessing database table. It does this using the register_current_processing SQL function.

If the log is currently being processed elsewhere then the method will return false (zero). If it has already been processed and readall is false then the method will return false (zero). If this is a new log, or readall is set to true, and the start of processing is successfully registered then the method will return true (one).

Do not call this method inside a transaction as this might lead to a long-term lock being taken which blocks any other processes.

end_processing($logname)

When the processing of a log is completed this method should be used to remove the associated entry from the currentprocessing table.

Do not call this method inside a transaction as this might lead to a long-term lock being taken which blocks any other processes.

begin_transaction

This is a simple wrapper to make it easier to start a new transaction. Internally it calls the txn_begin schema object method.

end_transaction

This is a simple wrapper to make it easier to end a transaction. Internally it calls the txn_commit schema object method.

register_log( $logname, $digest )

This method is used to register that processing of a log has been completed. The SHA digest of the file contents is stored so that processes can avoid reparsing a file that has not changed at some later date.

check_log_seen( $logname, $digest )

This method will check if a log has already been processed based on the contents of the SHA digest of its contents. It will return true (one) if it has been previously seen or false (zero) otherwise.

register_event($event)

This takes a reference to a hash which contains values for all the attributes which should be stored in the event table for this log entry.

The following attributes are required: raw, digest, logtime, hostname, message. The following attributes are optional: program, pid, userid. Further to this, a tags entry can be specified which will result in tags for this event being stored in the tag table. Values for any other hash keys will be ignored.

Note that the logtime attribute must be a DateTime object, that will be automatically formatted correctly by DBIx::Class.

check_event_seen($event)

This takes a reference to a hash which contains, at the very least, a digest key which refers to the SHA digest of the complete log entry. It will return true (one) if it has been previously seen or false (zero) otherwise.

CONFIGURATION AND ENVIRONMENT

The BuzzSaw database schema is only known to work with PostgreSQL, reports of success with other database types (or patches to add the necessary support) would be very welcome.

DEPENDENCIES

This module is powered by Moose. You will also need MooseX::Types, MooseX::Log::Log4perl and MooseX::SimpleConfig.

This module provides an interface to the BuzzSaw DBIx::Class schema class. You will also need a DBI driver module such as DBD::Pg.

SEE ALSO

BuzzSaw, BuzzSaw::DB::Schema

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.