Logging

Overview

There are two logging systems implemented in the Sugar application: SugarLogger and PSR-3. PSR-3 is Sugar's preferred logger solution and should be used going forward.

PSR-3

PSR-3 compliant logging solution has been implemented based on PHP Monolog. 

Log Levels

When you specify a logging level, the system will record messages for the specified level as well as all higher levels. For example, if you specify "Error", the system records all Error, Fatal, and Security messages. More information on logging levels can be found in the logger level configuration documentation.

Considerations

• When you are not troubleshooting Sugar, the log level should be set to Fatal in Admin > System Settings > Logger Settings to ensure that your environment is not wasting unnecessary resources to write to the Sugar log.

Logging Messages

The PSR-3 implementation in Sugar can also be used to log messages to the Sugar Log file. You can utilize the implementation to log to the Sugar log file using the default channel or you can specify your own custom channel if you want further control over when your custom logs should be displayed. 

  use \Sugarcrm\Sugarcrm\Logger\Factory;

//Get the default Logger
$Logger = Factory::getLogger('default');
$Logger->debug('Debug level message'); 
$Logger->info('Info level message'); 
$Logger->notice('Notice level message');
$Logger->warning('Warning level message'); 
$Logger->error('Error level message'); 
$Logger->critical('Critical level message');
$Logger->alert('Alert level message');
$Logger->emergency('Emergency level message');

//Get a custom Log Channel
$Logger = Factory::getLogger('my_logger');

Note: For more information on using custom channels, adding custom log handlers and processors see the PSR-3 Logger documentation.

SugarLogger

The SugarLogger class, located in ./include/SugarLogger/SugarLogger.php, allows for developers and system administrators to log system events to a log file. Sugar then determines which events to write to the log based on the system's Log Level. This can be set in Admin > System Settings.

Log Levels

When you specify a logging level, the system will record messages for the specified level as well as all higher levels. For example, if you specify "Error", the system records all Error, Fatal, and Security messages. More information on logging levels can be found in the logger level documentation.

Considerations

• When you are not troubleshooting Sugar, the log level should be set to Fatal in Admin > System Settings > Logger Settings to ensure that your environment is not wasting unnecessary resources to write to the Sugar log.

Logging Messages

Using $GLOBALS['log']

How to log messages using $GLOBALS['log'] in the system.

  $GLOBALS['log']->debug('Debug level message'); 
$GLOBALS['log']->info('Info level message'); 
$GLOBALS['log']->warn('Warn level message');
$GLOBALS['log']->deprecated('Deprecated level message');
$GLOBALS['log']->error('Error level message');
$GLOBALS['log']->fatal('Fatal level message');
$GLOBALS['log']->security('Security level message');

For more information on the implementation, please refer to the SugarLogger documentation. 

Using LoggerManager

How to log messages using the LoggerManager. 

  $Logger = \LoggerManager::getLogger();
$Logger->debug('Debug level message');
$Logger->info('Info level message');
$Logger->warn('Warn level message');
$Logger->deprecated('Deprecated level message');
$Logger->error('Error level message');
$Logger->fatal('Fatal level message');
$Logger->security('Security level message');

For more information on the implementation, please refer to the SugarLogger documentation. 

Log Rotation

The SugarLogger will automatically rotate the logs when the logger.file.maxSize configuration setting has been met or exceeded. When this happens, the Sugar log will be renamed with an integer. For example, if the Sugar log was named "sugarcrm.log, it will then be renamed "sugarcrm_1.log". The next log rotation after that would create "sugarcrm_2.log". This will occur until the logger.file.maxLogs configuration setting has been met. Once met, the log rollover will start over.

Debugging Messages with _ppl()

When developing, it may be beneficial for a developer to use _ppl() method to log a message to the Sugar log. The _ppl() method handles converting Objects, so you can quickly dump an entire object to the log while testing during development. 

  _ppl('Debugging message');

This will write a message to the Sugar log that defines the message and file location. An example is shown below:

  ------------------------------ _ppLogger() output start -----------------------------

Debugging message

------------------------------ _ppLogger() output end -----------------------------

------------------------------ _ppLogger() file: myFile.php line#: 5-----------------------------

 Note: It is important that you remove _ppl() from your code for production use as it will affect system performance.