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
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.
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.