SugarCRM SupportProduct GuidesSugar DeveloperSugar Developer Guide 10.3ArchitectureLogging
This release is only available for SugarCloud customers.

Logging

Overview

There are two logging systems implemented in the Sugar application: SugarLogger and PSR-3SugarLogger is the default logger that Sugar uses while codebase is migrated to PSR-3

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

Log Level Description
Debug Logs events that help in debugging the application
Info Logs informational messages and database queries
Warn Logs potentially harmful events
Deprecated Logs messages for deprecated methods that are still in use.
Error Logs error events in the application
Fatal Logs severe error events that may cause the application to abort. This is the default and recommended level.
Security Logs events that may compromise the security of the application
Off Logging is turned off

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.

PSR-3

As of Sugar 7.9, a PSR-3 compliant logging solution has been implemented based on PHP Monolog. 

Log Levels

Log Level Description
Debug Logs events that help in debugging the application
Info Logs informational messages and database queries
Warning Logs potentially harmful events
Notice Logs messages for deprecated methods that are still in use.
Error Logs error events in the application
Alert Logs severe error events that may cause the application to abort. This is the default and recommended level.
Critical Logs events that may compromise the security of the application
Off Turns off all logging

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.

Topics

    Custom loggers, defined in ./custom/include/SugarLogger/, can be used to write log entries to a centralized application management tool or to write messages to a developer tool such as FirePHP.
    Monolog\Handler\HandlerInterface
    The SugarLogger is used for log reporting by the application. The following article outlines the LoggerTemplate interface as well as the LoggerManager object and explains how to programmatically use the SugarLogger.

Last modified: 2021-01-06 23:28:41