Guillaume Aubert > Audit-DBI-1.7.1 > Audit::DBI

Download:
Audit-DBI-1.7.1.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: v1.7.1   Source   Latest Release: Audit-DBI-v1.8.2

NAME ^

Audit::DBI - Audit data changes in your code and store searchable log records in a database.

VERSION ^

Version 1.7.1

SYNOPSIS ^

        use Audit::DBI;
        
        # Create the audit object.
        my $audit = Audit::DBI->new(
                database_handle => $dbh,
        );
        
        # Create the necessary tables.
        $audit->create_tables();
        
        # Record an audit event.
        $audit->record(
                event               => $event,
                subject_type        => $subject_type,
                subject_id          => $subject_id,
                event_time          => $event_time,
                diff                => [ $old_structure, $new_structure ],
                search_data         => \%search_data,
                information         => \%information,
                affected_account_id => $account_id,
                file                => $file,
                line                => $line,
        );
        
        # Search audit events.
        my $audit_events = $audit->review(
                [ search criteria ]
        );

FORCE OBJECT STRINGIFICATION ^

When data structures are dumped (for diffs or to store information), it is sometimes desirable to turn some of the objects into strings, for two reasons:

A good example of this is Math::Currency. To convert those objects to strings, you can use the following:

        local $Audit::DBI::FORCE_OBJECT_STRINGIFICATION =
        {
                'Math::Currency' => 'bstr',
        };

METHODS ^

new()

Create a new Audit::DBI object.

        my $audit = Audit::DBI->new(
                database_handle => $dbh,
        );

Parameters:

record()

Record an audit event along with information on the context and data changed.

        $audit->record(
                event               => $event,
                subject_type        => $subject_type,
                subject_id          => $subject_id,
                event_time          => $event_time,
                diff                =>
                [
                        $old_structure,
                        $new_structure,
                ],
                search_data         => \%search_data,
                information         => \%information,
                affected_account_id => $account_id,
                file                => $file,
                line                => $line,
        );

Required:

Optional:

Notes:

review()

Return the logged audit events corresponding to the criteria passed as parameter.

        my $results = $audit->review(
                ip_ranges   =>
                [
                        {
                                include => $boolean,
                                begin   => $begin,
                                end     => $end
                        },
                        ...
                ],
                subjects    =>
                [
                        {
                                include => $boolean,
                                type    => $type1,
                                ids     => \@id1,
                        },
                        {
                                include => $boolean,
                                type    => $type2,
                                ids     => \@id2,
                        },
                        ...
                ],
                date_ranges =>
                [
                        {
                                include => $boolean,
                                begin   => $begin,
                                end     => $end
                        },
                        ...
                ],
                values      =>
                [
                        {
                                include => $boolean,
                                name    => $name1,
                                values  => \@value1,
                        },
                        {
                                include => $boolean,
                                name    => $name2,
                                values  => \@value2,
                        },
                        ...
                ],
                events      =>
                [
                        {
                                include => $boolean,
                                event   => $event,
                        },
                        ...
                ],
                logged_in   =>
                [
                        {
                                include    => $boolean,
                                account_id => $account_id,
                        },
                        ...
                ],
                affected    =>
                [
                        {
                                include    => $boolean,
                                account_id => $account_id,
                        },
                        ...
                ],
        );

All the parameters are optional, but at least one of them is required due to the sheer volume of data this module tends to generate. If multiple parameters are passed, they are additive, i.e. use AND to combine themselves.

Optional parameters that are not search criteria:

create_tables()

Create the tables required to store audit events.

        $audit->create_tables(
                drop_if_exist => $boolean,      #default 0
                database_type => $database_type #default SQLite
        );

ACCESSORS ^

get_database_handle()

Return the database handle tied to the audit object.

        my $database_handle = $audit->_get_database_handle();

get_memcache()

Return the database handle tied to the audit object.

        my $memcache = $audit->get_memcache();

INTERNAL METHODS ^

get_cache()

Get a value from the cache.

        my $value = $audit->get_cache( key => $key );

set_cache()

Set a value into the cache.

        $audit->set_cache(
                key         => $key,
                value       => $value,
                expire_time => $expire_time,
        );

insert_event()

Insert an audit event in the database.

        my $audit_event = $audit->insert_event( \%data );

Important: note that this is an internal function that record() calls. You should be using record() instead. What you can do with this function is to subclass it if you need to extend/change how events are inserted, for example:

AUTHOR ^

Guillaume Aubert, <aubertg at cpan.org>.

BUGS ^

Please report any bugs or feature requests through the web interface at https://github.com/guillaumeaubert/Audit-DBI/issues/new. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc Audit::DBI

You can also look for information at:

ACKNOWLEDGEMENTS ^

Thanks to ThinkGeek (http://www.thinkgeek.com/) and its corporate overlords at Geeknet (http://www.geek.net/), for footing the bill while I write code for them!

Thanks to Nathan Gray (KOLIBRIE) for implementing rate limiting in record() calls in v1.3.0.

Thanks to Kate Kirby (KATE) for pair-programming on the implementation of the stringification feature in v1.5.0.

COPYRIGHT & LICENSE ^

Copyright 2010-2013 Guillaume Aubert.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/

syntax highlighting: