NAME

Konstrukt::Plugin::log - Konstrukt logging facilities.

SYNOPSIS

        <!-- add a log entry.
             key1-5 are optional. -->
        <& log
                action="put" 
           type="login"
           description="user 'foo' logged in"
           key1="some additional info"
           key2="some additional info"
           key3="some additional info"
           key4="some additional info"
           key5="some additional info"
        / &>
        
        <!-- display log entries -->
        <& log
           type="log type"
           keycount="number of additional keys to display"
           orderby="column"
           limit="42"
        / &>

DESCRIPTION

This module allows for logging to a given backend (like a DBI database).

Each log entry has an automatically generated timestamp and client address, a type, which may be used to identify several loggin sources (plugin name, etc.), a human readable description and 5 additional keys which may be up to 255 chars long each and can be used as needed.

The perl-interface looks like this:

        my $log = use_plugin 'log';
        
        #add entry. the keys are optional
        $log->put("type", "description", "key1", "key2", "key3", "key4", "key5");
        
        #retrieve log entries of type "type" and order them by key2, key1 and key3.
        my $entries = $log->get("type", "key2, key1, key3");
        #$entries is an array reference to hash-references:
        #$entries =
                [
                        { year => 1234, month => 12, day => 12, hour => 12, minute => 12,
                          host => '192.168.0.1',
                          type => "type",
                          description => "description",
                          key1 => "key 1", key2 = "..." ... },
                        ...
                ]
        print $entries->[3]->{description}

The Konstrukt-interface looks like this:

        <!-- add a new entry -->
        <& log action="put" type="type" description="some log entry" key1="key 1 value" key2="..." / &>
        
        <!-- print out a list in template-syntax. (default action)
             The type attribute determines the type of the log entries to show.
             If not defined, all types will be shown.
             The keycount attribute determines how many keys are used in the log entries.
             The orderby and limit attributes will be passed as-is to the DBI query. -->
        <& log type="type" keycount="3" orderby="key2, key1, key3" key1_name="foo" key2_name="bar" key3_name="baz" limit="20" / &>
        <!-- note: you may also order by the column "timestamp" -->

CONFIGURATION

You have to do some configuration in your konstrukt.settings to let the plugin know where to get its data and which layout to use. Defaults:

        #log
        log/use              0
        log/backend          DBI
        log/template_path    /templates/log/ #path to the log templates
        log/sendmail           #send mails to this account (user@host.tld) for each new log entry
        log/sendmail_ignore    #space separated list of stings. if the subject or content of
                               #a message contains any of these strings, no mail will be sent.
                               #note that a substring match will be made: 'usermanagement' will
                               #block 'usermanagement::basic' as well as 'confusermanagement::foo'.
                               #to match a string with whitespaces, put it into doublequotes.
        #access control
        log/userlevel_view   1 #userlevel to view the logs
        log/userlevel_clear  2 #userlevel to clear the logs

Mails will be sent through "mail" in Konstrukt::Lib.

See the documentation of the backend modules (e.g. "CONFIGURATION" in Konstrukt::Plugin::usermanagement::basic::DBI) for their configuration.

        #messages
        log/template_path    /log/

METHODS

execute_again

Yes, this plugin may return dynamic nodes (i.e. template nodes).

init

Initializes this object. Sets $self->{backend} and $self->{layout_path}. init will be called by the constructor.

install

Installs the templates.

Parameters:

none

prepare

We cannot prepare anything as the input data may be different on each request. The result is completely dynamic.

execute

All the work is done in the execute step.

put

Adds a new log entry.

Parameters:

$type - The type/source of this entry
$description - A human readable description
($key1 - $key5) - Optional additional keys

get

Returns the requested log entries as an array reference of hash references.