Ivan Wills

NAME

Log::Deep - Deep Logging of information about a script state

VERSION

This documentation refers to Log::Deep version 0.3.3.

SYNOPSIS

   use Log::Deep;

   # create or append a log file with the current users name in the current
   # directory (if possible) else in the tmp directory. The session id will be
   # randomly generated.
   my $log = Log::Deep->new();

   $log->debug({-data => $object}, 'Message text');

DESCRIPTION

Log::Deep creates a object for detailed logging of the state of the running script.

Plugins

One of the aims of Log::Deep is to be able to record deeper information about the state of a running script. For example a CGI script (using CGI.pm) has a CGI query object which stores its parameters and cookies, using the CGI plugin this extra information is logged in the data section of the log file.

Some plugins add data only when the a logging session starts, others will add data every time a log message is written.

The Log File

Log::Deep log file format looks something like

 iso-timestamp;session id;level;message;caller;data

All values are url encoded so that one log line will always represent one log message, the line should be reasonably human readable except for the data section which is a dump of all the deep details logged. A script deeper is provided with Log::Deeper that allows for easier reading/searching of Log::Deep log files.

SUBROUTINES/METHODS

new ( %args )

Arg: -level - array ref | string - If an array ref turns on all levels specified, if a string turns on that level and higher

Arg: -file - string - The name of the log file to write to

Arg: -log_dir - string - The name of the directory that the log file is written to.

Arg: -name - string - The name of the file in -log_dir

Arg: -date_fmt - string - The date format to use for appending to log file -names

Arg: -style - -

Arg: -rand_max - -

Arg: -session_id - string - A specific session id to use.

Return: Log::Deep - A new Log::Deep object

Description: This creates a new log object.

info ( $var )

Param: $ - type -

Return: -

Description:

message ( $var )

Param: $ - type -

Return: -

Description:

debug ( $var )

Param: $ - type -

Return: -

Description:

warn ( $var )

Param: $ - type -

Return: -

Description:

error ( $var )

Param: $ - type -

Return: -

Description:

fatal ( $var )

Param: $ - type -

Return: -

Description:

security ( $var )

Param: $ - type -

Return: -

Description:

record ( $var )

Param: $ - type -

Return: -

Description:

log_handle ( $var )

Param: $ - type -

Return: -

Description:

session ( $var )

Param: $ - type -

Return: -

Description:

level ( $var )

Param: $ - type -

Return: -

Description:

enable (@levels)

Param: @levels - strings - The names of levels to enable

Description: Enables the supplied levels

disable (@levels)

Param: @levels - strings - The names of levels to disable

Description: Disables the supplied levels

is_info ()

Return: bool - True if the info log level is enabled

Description:

is_message ()

Return: bool - True if the message log level is enabled

Description:

is_debug ()

Return: bool - True if the debug log level is enabled

Description:

is_warn ()

Return: bool - True if the warn log level is enabled

Description:

is_error ()

Return: bool - True if the error log level is enabled

Description:

is_fatal ()

Return: bool - True if the fatal log level is enabled

Description:

is_security ()

Return: bool - True if the security log level is enabled

Description:

file ( $var )

Return: string - The file name of the currently being written to log file

Description: Gets the file name of the current log file

catch_warnings ( $action )

Param: $action - 1 | 0 | undef - Set catch warnings (1), unset catch warnings (0) or report state (undef)

Return: bool - True if currently catching warnings, false if not

Description: Turns on/off catching warnings and/or returns the current warn catching state.

flush ()

Description: Calls IO::Handle's flush on the log file handle

DIAGNOSTICS

CONFIGURATION AND ENVIRONMENT

DEPENDENCIES

INCOMPATIBILITIES

BUGS AND LIMITATIONS

There are no known bugs in this module.

Please report problems to Ivan Wills (ivan.wills@gmail.com).

Patches are welcome.

AUTHOR

Ivan Wills - (ivan.wills@gmail.com)

LICENSE AND COPYRIGHT

Copyright (c) 2009 Ivan Wills (14 Mullion Close, Hornsby Heights, NSW 2077). All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. 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.