Software Development Kit

cPanel & WHM's API [+] cPanel & WHM's API [-]

Modules and Plugins [+] Modules and Plugins [-]

cPanel & WHM Hooks [+] cPanel & WHM Hooks [-]

cPAddons (Site Software) [+] cPAddons (Site Software) [-]

System Administration [+] System Administration [-]

Developer Software [+] Developer Software [-]

Back to All Documentation

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

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 Note: Custom event handlers execute as the user who initiated That means that any user who may initiate a custom event handler must have permission to write to the specified log file.


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


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


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/ line 31
	Cpanel::CustomEventHandler::event(2, 'pre', 'email', 'addpop', HASH(0x94df8b4), undef) called at /usr/local/cpanel/Cpanel/ line 63
	Cpanel::EventHandler::event(2, 'pre', 'email', 'addpop', HASH(0x94df8b4)) called at line 3970
	main::api2_exec('Email', 'addpop', HASH(0xb8f108c), HASH(0x94df8b4)) called at line 668
	main::docpanelaction(HASH(0xb8e2b80)) called at line 4915
	main::run_fast_json_mode() called at 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.

Topic revision: r9 - 17 Feb 2011 - 19:33:16 - Main.JustinSchaefer