cPanel's Logger Module

The Cpanel::Logger module can be used to raise error messages in a custom event handler. This module provides a common interface for logging to files, such as cPanel's error_log.

Using Cpanel::Logger

In order to use this module, you must state the following in CustomEventHandler.pm.

use Cpanel::Logger;

sub event {
my $logger= Cpanel::Logger->new();

Specifying a Log File

To define the file to which Cpanel::Logger will log, you must use the new() function. The new() function must be called with a hash reference that contains the alternate_logfile. This variable should hold the location of the file to which you wish to log.

my $logger = Cpanel::Logger->new( { alternate_logfile => /path/to/log_file } );

Note: Custom event handlers execute as the user who initiated CustomEventHandler.pm. That means that any user who may initiate a custom event handler must have permission to write to the specified log file.

Functions

There are a few different functions that are used to log to cPanel's error_log.

info()

The info() function displays an error message with a time stamp. It is called with a single parameter that contains the message to be printed to the log file.

$logger->info("this is an error message");

The code above will print the following into the error_log:

• YYYY-MM-DD HH:MM:SS info [cpanel] this is an error message

warn()

The warn() function displays an error message accompanied with a backtrace. This means that it will show the API call. When using the warn() function, the output should resemble the following:

[YYYY-MM-DD HH:MM:SS TZ] warn [cpanel] This is an error message at /usr/local/cpanel/Cpanel/CustomEventHandler.pm line 31
	Cpanel::CustomEventHandler::event(2, 'pre', 'email', 'addpop', HASH(0x94df8b4), undef) called at /usr/local/cpanel/Cpanel/EventHandler.pm line 63
	Cpanel::EventHandler::event(2, 'pre', 'email', 'addpop', HASH(0x94df8b4)) called at cpanel.pl line 3970
	main::api2_exec('Email', 'addpop', HASH(0xb8f108c), HASH(0x94df8b4)) called at cpanel.pl line 668
	main::docpanelaction(HASH(0xb8e2b80)) called at cpanel.pl line 4915
	main::run_fast_json_mode() called at cpanel.pl line 341

As you can see from the example above, the warn() function will show the internal functions as they are used during the process. When called in an HTML page, the warn() function will also display the page from which it was generated.