The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

BGPmon::Log - BGPmon Logging

This module implements logging for BGPmon clients. The module can log messages to syslog, STDERR, or a user specified log file. It allows the user to specify a log level and write log messages using different log levels.

SYNOPSIS

After initializing the log, the user can log messages at different log levels.

use BGPmon::Log qw (debug log_debug log_info log_notice log_warn log_warning log_err log_error log_fatal log_crit log_critical log_alert log_emerg log_emergency );

my %log_param = ( prog_name => "my name", log_level => BGPmon::Log::LOG_DEBUG(), log_facility => BGPmon::Log::LOG_LOCAL0(), log_file => "./mylog", use_syslog => 0, use_gmt => 0, );

if (BGPmon::Log::log_init(%log_param) ) { my $code = BGPmon::Log::get_error_code("log_init"); my $msg = BGPmon::Log::get_error_message("log_init"); print STDERR "Error initializing log: $code - $msg\n"; exit 1; }

debug("Log a message with level BGPmon::Log::LOG_DEBUG");

log_debug("Also log a message with level BGPmon::Log::LOG_DEBUG");

log_info("Log a message, level BGPmon::Log::LOG_INFO");

log_notice("Log a message, level BGPmon::Log::LOG_NOTICE");

log_warn("Log a message, level BGPmon::Log::LOG_WARN");

log_warning("Log a message, level BGPmon::Log::LOG_WARNING");

log_err("Log a message, level BGPmon::Log::LOG_ERR");

log_error("Log a message, level BGPmon::Log::LOG_ERROR");

log_fatal("Log a message, level BGPmon::Log::LOG_FATAL");

log_crit("Log a message, level BGPmon::Log::LOG_CRIT");

log_critical("Log a message, level BGPmon::Log::LOG_CRITICAL");

log_alert("Log a message, level BGPmon::Log::LOG_ALERT");

log_emergency("Log a message, level BGPmon::Log::LOG_EMERGENCY");

log_emerg("Log a message, level BGPmon::Log::LOG_EMERG");

BGPmon::Log::log_close();

EXPORT

log_init log_close log_emerg log_emergency log_alert log_fatal log_crit log_critical log_err log_error log_warn log_warning log_notice log_info log_debug debug get_errror_code get_error_message get_error_msg

SUBROUTINES/METHODS

log_init

Initialize the logging facility. This function must be called prior to using any log_* functions.

Input : The log settings 1. prog_name - The program name 2. log_level - the log level 3. log_facility - the log facility 4. log_file - the file where log messages will be written 5. use_syslog - flag indicating whether to use syslog, 1 = use syslog, 5. use_gmt - flag indicating whether to GMT for time or use local time, 1 = use GMT, use_gmt can only be set when use_syslog = 0 Output: returns 0 on success, 1 on error and setserror_message and error_code

If use_syslog=1, all log messages are written to syslog. if the user sets both use_syslog=1 and provides a log_file, the log_file is ignored.

If use_syslog != 1, log messages are written to the log_file, if provided if no log file is provided to init, all messages are written to STDERR

log_close

Closes the logfile so no further log messages can be written You must call log_init again to re-enable logging.

Typically called at the end of program to cleanly close the log file or cleanly close the connection to syslog.

Input: None Output: None

log_emerg

Logs an emergency message. Log levels LOG_EMERG

Input: Message to be printed. Output: returns 0 on success, 1 on error and sets error_message and error_code

log_emergency

Logs an emergency message. Log levels LOG_EMERGENCY

This function is identical to log_emerg

log_alert

Logs an alert message. Log levels LOG_ALERT

Input: Message to be printed. Output: returns 0 on success, 1 on error and sets error_message and error_code

log_fatal Logs a fatal error message. Log levels LOG_CRIT

Input: Message to be printed. Output: returns 0 on success, 1 on error and sets error_message and error_code

log_crit Logs a critical error message. Log levels LOG_CRIT

This function is identical to log_fatal

log_critical

Logs a critical error message. Log levels LOG_CRIT

This function is identical to log_fatal

log_err

Logs an error message. Log level LOG_ERR. Input: Message to be printed. Output: returns 0 on success, 1 on error and sets error_message and error_code

log_error

Logs an error message. Log level LOG_ERR.

This function is identical to log_fatal

log_warn

Logs a warning message. Log level LOG_WARN This function is identical to log_fatal Input: Message to be printed. Output: returns 0 on success, 1 on error and sets error_message and error_code

log_warning

Logs a warning message. Log level LOG_WARNING

This function is identical to log_warn

log_notice

Logs a notice message. Log level LOG_NOTICE Input: Message to be printed. Output: returns 0 on success, 1 on error and sets error_message and error_code

log_info

Logs a informational message. Log level LOG_INFO Input: Message to be printed. Output: returns 0 on success, 1 on error and sets error_message and error_code

log_debug

Logs a debug message. Log level LOG_DEBUG Input: Message to be printed. Output: returns 0 on success, 1 on error and sets error_message and error_code

debug

Logs a debug message. Log level LOG_DEBUG

This function is identical to log_debug

get_error_code

Get the error code Input : the name of the function whose error code we should report Output: the function's error code or NO_FUNCTION_SPECIFIED if the user did not supply a function or INVALID_FUNCTION_SPECIFIED if the user provided an invalid function

get_error_message

Get the error message Input : the name of the function whose error message we should report Output: the function's error message or NO_FUNCTION_SPECIFIED if the user did not supply a function or INVALID_FUNCTION_SPECIFIED if the user provided an invalid function

get_error_msg

Get the error message

This function is identical to get_error_message

RETURN VALUES AND ERROR CODES

All functions return 0 on success and 1 on error. In the event of an error, an error code and error message can be obtained using $code = get_error_code("function_name"); $msg = get_error_msg("function_name");

The following error codes are defined:

 0 - No Error:
     'No Error'

 1 - No Function Specified in get_error_code/get_error_msg
    'Error reporting function called without specifying the function.'

 2 - Invalid Funtion in get_error_code/get_error_msg
    'Error reporting function called with invalid function name'

 3 - Failed To Obtain Hostname in log_init
    'Unable to get the hostname'

 4 - Program Name Exceeds Max Length in log_init
    'Program name exceeds maximum length of MAX_STRING_LEN'

 5 - Program Name Contains Non-Printable Characters in log_init
    'Program name contains non-printable characters'

 6 - Log Level Is Not A Number in log_init
    'Log level must be a postive integer'

 7 - Log Level Is Out of Range in log_init
    'Log level must be between LOG_EMERG and LOG_DEBUG'

 8 - Log Facility Is Not A Number in log_init
    'Log facility must be a postive integer'

 9 - Log File Name Exceeds Max Length in log_init
    'Log file exceeds maximum length of MAX_STRING_LEN'

 10 - Log File Name Contains Non-Printable Characters in log_init
    'Log file contains non-printable characters'

 11 - Use_syslog Is Not A Number in log_init
    'use_syslog must be 0 or 1'

 12 - Use_syslog Is Not 0 or 1 in log_init
    'use_syslog must be 0 or 1'

 13 - Use_gmt Is Not A Number in log_init
    'use_gmt must be 0 or 1'

 14 - Use_gmt Is Not 0 or 1 in log_init
    'use_gmt must be 0 or 1'

 15 - Use_gmt Set When Use_syslog = 1 in log_init
    'use_gmt not allowed when use_syslog = 1'

 16 - Specified Both Syslog and Log File in log_init
   'Unable to both use_syslog and write to file ';

 17 - Unable To Open Syslog in log_init
   'Unable To open syslog';

 18 - Unable To Open Log File in log_init
   'Unable to open log file';

 19 - Log Function Called Before Log Initialized
   'Logging not initialized.   Use init_log() prior to calling log_*("msg")';

 20 -No Such Log Function Exists
   'No such log function ';

 21 - No Message to Log
   'Log function called with no log message';

 22 - Log Message Exceeds Maximum Length
    'Log message exceeds maximum length of '.MAX_STRING_LEN;

 23 - Log Message Contains Non-Printable Characters
    'Message name contains non-printable characters'

 24 - Failed to Write Log Message
   'Unable to write log messsage ';

AUTHOR

Dan Massey, <massey at cs.colostate.edu>

BUGS

Please report any bugs or feature requests to <bgpmon@netsec.colostate.edu>.

SUPPORT

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

    perldoc BGPmon::Log

LICENSE AND COPYRIGHT

Copyright (c) 2012 Colorado State University

    Permission is hereby granted, free of charge, to any person
    obtaining a copy of this software and associated documentation
    files (the "Software"), to deal in the Software without
    restriction, including without limitation the rights to use,
    copy, modify, merge, publish, distribute, sublicense, and/or
    sell copies of the Software, and to permit persons to whom
    the Software is furnished to do so, subject to the following
    conditions:

    The above copyright notice and this permission notice shall be
    included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
    OTHER DEALINGS IN THE SOFTWARE.\

    File: Log.pm

    Authors: Kaustubh Gadkari, Dan Massey, Cathie Olschanowsky
    Date: May 21, 2012

    Updated documentation and error reporting:  Dan Massey
    Date: July 9, 2012