NAME

 Fault::Delegate::DB - Database Logger Delegate.

SYNOPSIS

 use Fault::Delegate::DB;
 $self = Fault::Delegate::DB->new ($host,$host,$dbname,$user,$pass);
 $okay = $self->log               ($msg);
 $zero = $self->trans01           ($msg);
 $zero = $self->trans10           ($msg);
 @list = $self->initfaults;

Inheritance

 UNIVERSAL
   Fault::Delegate
     Fault::Delegate::DB

Description

This is a Logger delegate for database logging.

This Class manages a database logging connection to a local Mysql database server.

Remote database access is not supported at this time. It will require changes to the Fault::Dbh module, or improvements in MySQL (and total disappearance of old versions) which prevent exhaustion of connections if your processes rapidly create and destroy connections.

Also note that some attempt has been made to be thread-safe. I discovered that if a handle was created in a parent there was a possibility it could be reused in a child process. The parent and child then had interleaved communications with the server which completely confused it.

Database requirements

There should be two tables defined on the MySQL database server under the same database: log and fault. You must have a username and password that give you rights to select, insert and delete from them.

 use Mydatabase;
 CREATE TABLE log ( \
    LogId       bigint unsigned auto_increment, \
    Time        datetime                       NOT NULL, \
    Priority    enum('emerg','alert','crit','err','warning','notice','info','debug') NOT NULL DEFAULT 'err', \
    Process     varchar(20)                    NOT NULL DEFAULT 'Unspecified', \
    Type        enum('BUG','SRV','NET','DATA','NOTE') NOT NULL DEFAULT 'BUG', \
    Message     blob                           NOT NULL, \
 UNIQUE (LogId), \
 PRIMARY KEY  (LogId));
 

 CREATE TABLE faults ( \
    FaultId          bigint unsigned auto_increment, \
    Time             datetime                   NOT NULL, \
    Priority         enum('emerg','alert','crit','err','warning','notice','info','debug') NOT NULL DEFAULT 'err', \
    Process          varchar(20)                NOT NULL DEFAULT 'Unspecified', \
    Type             enum('BUG','SRV','NET','DATA','NOTE') NOT NULL DEFAULT 'BUG', \
    Message          blob                       NOT NULL, \
 UNIQUE (FaultId), \
 PRIMARY KEY  (FaultId));

Examples

 use Fault::Delegate::DB;
 use Fault::Msg;
 use Fault::Logger;

 my $msg       = Fault::Msg               ("Arf!");
 my $baz       = Fault::Delegate::DB->new ($host,$db,$user,$pass);
 my $waslogged = $baz->log                ($msg);

                 Fault::Logger->new       ($baz);
 my $waslogged = Fault::Logger->log       ("Bow! Wow!");

 [See Fault::Logger for a detailed example.]

Class Variables

None.

Instance Variables

 host           Name of host computer.
 dbname         Name of database.
 user           Name of user.
 pass           Password string.

 Transient instance variables.
 dbh            database handle.
 logins         prepared log insert statement handle 
 faultins       prepared fault insert statement handle 
 sthdel         prepared fault delete statement handle 
 sthlist        prepared fault select all statement handle 
 sthexist       prepared fault select one statement handle 

Class Methods

$self = Fault::Delegate::DB->new ($host,$dbname,$user,$pass)

Create an object to mediate log and fault communications with a database server. It has only been tested with MySQL thus far.

$host can only be "localhost" at this time. If undef, $host will be set to localhost. If $host is invalid in any other way, a warning will be issued and $host will be set to localhost.

$dname is the name of the MySQL database in which the tables log and fault exist; $user is a user name that can read and write those tables; $pass is that users MySQL password.

Returns undef on failure to create the object and connect to the db.

Instance Methods

$okay = $self->log ($msgobj)

Inserts a log message in the database and returns true if we succeeded in doing so.

$zero = $self->trans01 ($msgobj)

Inserts a fault record for the current process name and the $msg string. If one already exists, do nothing. It always returns 0.

$zero = $self->trans10 ($msgobj)

Removes a fault record that matches the current process name and the $msg string. If there is not, do nothing. It always returns 0.

@list = $self->initfaults

Requests a current list of faults from the database when Logger initializes. @list contains a simple list of strings, where each string represents a unique active fault condition belonging to the current process.

 ("fault message 1", "fault message 2", ...)

If it cannot connect to the database, an empty list is returned.

Private Class Methods

None.

Private Instance Methods

$bool = $self->_write ($msg)

$bool = $self->_connect

$bool = $self->_disconnect

Impliments the above overrides to the internal family protocol utilized by the Fault:Delegate log and test methods.

Errors and Warnings

Local warning messages are issued if the db server cannot be reached or has any problems whatever.

KNOWN BUGS

 See TODO.

SEE ALSO

Fault::Logger, Fault::Delegate, Fault::Msg, Fault::Dbh, Fault::ErrorHandler, Fault::DebugPrinter

AUTHOR

Dale Amon <amon@vnl.com>

cpanm Fault::Msg

perl -MCPAN -e shell
install Fault::Msg