SugarCRM Error Log

Sugar has a robust error tracking system.  It is one of the best tools that a developer can use to debug their code.  If you're writing custom code in Sugar it behooves you to understand how to use the Sugar error log to your benefit.  Sugar records a wealth of information to the error log, some think too much, but you can control that.  Let's take a closer look.

The Sugar error log is a file located in the top Sugar directory level called sugarcrm.log.    This is a text file you can bring up and look at in any text editor, like Notepad++.  The long hyphenated number in each log record is your user_id in Sugar in case more than one user is using the system, and thus will also be creating log entries.  Here's what the sugarcrm.log entries look like:

If you go to the back-end admin panel in "Admin->System Settings" and scan down the page, you'll find a subpanel at the bottom called "Logger Settings."  Here you can change the actual name of the the file and extension, the maximum size of the file, whether you want a date attached to the file name, and the log level, which I'll talk about below.   I would recommend you keep the default settings and leave it set up as is, which means your Sugar errors will go to the sugarcrm.log, and when that exceeds the default file size of 10MB, it will change that file name to sugarcrm_1.log, then sugarcrm_2.log, etc., and start a new sugarcrm.log.  This is handy, since all you need to be concerned with is one file, the most current log, the sugarcrm.log file.

Let's go a little beyond the admin panel.  The code controlling the Sugar log is located in include/SugarLogger.  The code that runs the logger and determines what is output is in SugarLogger.php.  I don't recommend you mess with this file unless you really know what your doing, but you can configure the format of what is outputted here.  For example, if you were the only one developing your system, you may want to take the user_id out of a log record.   There is a better way to control the amount of information outputted.  Let's take a look at the include/SugarLogger/LoggerManager.php file.

LoggerManager.php

LoggerManager.php

The $_level variable in the file is the Log Level set in Admin->System Settings->Log Level.   The array of log level mappings in LoggerManager.php correspond to the Log Level dropdown menu in the admin panel.  Log Level is important.  Sugar is very verbose in the amount of entries it makes to the sugarcrm.log.  You want to limit the entries in the log, because it can get very long, and you'll have trouble finding the entries you want to stand out in the mass of entries that are outputted.

To control the amount of entries in the log file, you can set the Log Level to "Fatal," for example, then only errors that are marked "Fatal" and lower in the array's number hierarchy are visible.  In the case of a "fatal" log level only errors marked fatal, security, special, dale, and off would show in the sugarcrm.log.  By changing the Log Level, you can control what is logged to the log.

Here's what the Log Level events mean in Sugar:

Debug : Logs events that help in debugging the application.
Info : Logs informational messages and database queries.
Warn : Logs potentially harmful events.
Error : Logs error events in the application.
Fatal : Logs severe error events that leads the application to abort. This is the default level.
Security : Logs events that may compromise the security of the application.

The reason I showed you the LoggerManager.php file is to show you that you can add your own special labels to the log levels dropdown by adding them to this array.  In the picture, I added the "special" and "dale" levels to use in my debugging which are not in the default package.  The advantage of this is you don't have to go back and change the log level when you want to cut down you log output to see your debugging output more easily.   Bear in mind, if you put your own log levels in the array in the LoggerManager.php file, that this is a core file, and your entries may be removed when you upgrade Sugar.

 

How do you create log entries in the sugarcrm.log file?

Most of the log entries are already embedded in the Sugar core code, which outputs error messages depending on the Log Level, as we just discussed.  However, the log can be made much more functional by creating your own log entries anywhere in the Sugar code, and I do mean anywhere, by adding a line to the code like this:

STRINGS

$GLOBALS['log']->special("Output this string to tell me where I am at in my code");

This will output the string, "Output this string to tell me where I am at in my code," right after [SPECIAL] in the sugarcrm.log record for this event. (See the first picture.)  In this example, you can substitute any of the Log Levels for special when you put this in your code.  That's it.

Let's look at what else you can output to the sugarcrm.log file.

VARIABLES
Are outputted, like so:

$GLOBALS['log']->dale("The accountid is: $accountid");

ARRAYS
Are outputted, like so:

$GLOBALS['log']->debug("The _POST from the detail view is: " . print_r($_POST, true));

 

In addition to variable and arrays, I've found it useful to output the PHP method with the log entry, like so:

$GLOBALS['log']->fatal("[teamAssignBefore] bean->modulename:  $bean->module_name");

Another useful trick when writing new code is to number the output from a series of log entries, so you can tell your progress through the code and whether you entered a conditional or not.  The numbers make it easy to follow your progress through the code, like so.

$GLOBALS['log']->dale("10 The accountid is: $accountid");
$GLOBALS['log']->dale("20 The account name is: $accountname");
$GLOBALS['log']->dale("30 The account city is: $accountcity");

If you have a conditional you can change the number endings, like so:

$GLOBALS['log']->dale("10 The accountid is: $accountid");
$GLOBALS['log']->dale("20 The account name is: $accountname");
$GLOBALS['log']->fatal("25 There is no account name in the record: $accountname");
$GLOBALS['log']->fatal("35 There is no account city in the record: $accountcity");
$GLOBALS['log']->dale("30 The account city is: $accountcity");

Depending on what I'm doing, I've also used the line number and file name for a quick reference to where the error occurred in a particular file.

There is one other error file you should be aware of is the php_error.log.  This log will output any PHP errors in your code.  Most of the time this will not have to be looked at unless, of course, you started getting those glaring orange PHP error boxes in your output.

When I'm coding in Sugar, I have my NetbeansIDE open on one monitor, where I write my code, and on my other monitor, I have the sugarcrm.log file open.  When I run my code, I immediately see my variables and arrays in the log, and thus immediately know what's happening in my code, and whether I'm getting the data I expect.  Happy coding!

Comments are closed.