Audit::DBI - Audit data changes in your code and store searchable log records in a database.
Version 1.4.0
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 ]
);
Create a new Audit::DBI object.
my $audit = Audit::DBI->new(
database_handle => $dbh,
);
Parameters:
Mandatory, a DBI object.
Optional, a Cache::Memcached or Cache::Memcached::Fast object to use for rate limiting. If not specified, rate-limiting functions will not be available.
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:
The type of action performed (48 characters maximum).
Normally, the singular form of the name of a table, such as "object" or "account" or "order".
If subject_type is a table, the corresponding record ID.
Optional:
This automatically calculates the differences between the two data structures passed as values for this parameter, and makes a new structure recording those differences.
A hashref of all the key/value pairs that we may want to be able search on later to find this type of event. You may pass either a scalar or an arrayref of multiple values for each key.
Any other useful information (such as user input) to understand the context of this change.
The ID of the account to which the data affected during that event where linked to, if applicable.
Unix timestamp of the time that the event occurred, the default being the current time.
The filename and line number where the event occurred, the default being the immediate caller of Audit::DBI->record().
Note: if you want to delay the insertion of audit events (to group them, for performance), subclass Audit::DBI and add a custom insert_event() method.
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.
Allows restricting the search to ranges of IPs. Must be given in integer format.
Allows searching on specific events.
Allows to search on the subject types and subject IDs passed when calling record(). Multiple subject types can be passed, and for each subject type multiple IDs can be passed, hence the use of an arrayref of hashes for this parameter. Using
[
{
type => $type1,
ids => \@id1,
},
{
type => $type2,
ids => \@id2,
}
]
would translate into
(subject_type = '[type1]' AND subject_id IN([ids1]) ) OR (subject_type = '[type2]' AND subject_id IN([ids2]) )
for searching purposes.
Allows restricting the search to specific date ranges.
Searches on the key/values pairs initially passed via 'search_data' to record().
Searches on the ID of the account that was logged in at the time of the record() call.
Searches on the ID of the account that was linked to the data that changed at the time of the record() call.
Create the tables required to store audit events.
$audit->create_tables(
drop_if_exist => $boolean, #default 0
database_type => $database_type #default SQLite
);
Return the database handle tied to the audit object.
my $database_handle = $audit->_get_database_handle();
Return the database handle tied to the audit object.
my $memcache = $audit->get_memcache();
Get a value from the cache.
my $value = $audit->get_cache( key => $key );
Set a value into the cache.
$audit->set_cache(
key => $key,
value => $value,
expire_time => $expire_time,
);
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:
Guillaume Aubert, <aubertg at cpan.org>.
Please report any bugs or feature requests to bug-audit-dbi at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Audit-DBI. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
perldoc Audit::DBI
You can also look for information at:
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.
Copyright 2012 Guillaume Aubert.
This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License.
See http://dev.perl.org/licenses/ for more information.
