Guillaume Aubert > Audit-DBI > Audit::DBI

Download:
Audit-DBI-v1.8.2.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: v1.8.2   Source  

NAME ^

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

VERSION ^

Version 1.8.2

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 ]
        );

To see an example of a search interface for audit events recorded by Audit::DBI, check the examples/ directory of Audit::DBI::TT2.

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:

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:

AUTHOR ^

Guillaume Aubert, <aubertg at cpan.org>.

CONTRIBUTORS ^

ACKNOWLEDGEMENTS ^

I originally developed this project for ThinkGeek (http://www.thinkgeek.com/). Thanks for allowing me to open-source it!

COPYRIGHT & LICENSE ^

Copyright 2010-2014 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: