Logging Service
The Log service is a logging mechanism in the HLEB2 framework that allows storing errors and messages in a dedicated log storage. The principle of log retention in the framework is based on PSR-3.
By default, the framework uses a built-in logging mechanism that saves logs to a file. All PHP errors and the operation of the application itself are logged, as well as informational and debug logs specified by the developer in the code.
The framework's standard file logs are stored in the project's /storage/logs/ folder.
Ways to use Log in controllers (and all classes inherited from Hleb\Base\Container) are exemplified by adding an informational message:
use Hleb\Reference\LogInterface;
$this->container->get(LogInterface::class)->info('Sample message');
// variant 2
$this->container->log()->info('Sample message');
Example of logging in application code:
use Hleb\Static\Container;
use Hleb\Reference\LogInterface;
$data = Container::get(LogInterface::class)->info('Sample message');
// variant 2
use Hleb\Static\Log;
Log::info('Sample message');
// variant 3
logger()->info('Sample message');
The Log object can also be obtained through dependency injection via the Hleb\Reference\Interface\Log interface.
For simplicity, examples hereafter will only use the function logger().
Executing one of the previous examples will create a log file in the /storage/logs/ directory (if it did not exist previously) with a line added similar to this:
The log text shows that a message 'Sample message' was output with a specified level 'INFO', along with additional information about the log call, precise time, and basic request data.
Confidential information and data within logs, whose disclosure could lead to security breaches of the project, are not recommended to be sent to third-party services for log storage as they can be susceptible to hacking.
#Logging Levels
When choosing a logging level, you should be guided by the content and importance of the data being output. The list from ordinary messages to critical errors in ascending order:
debug() - debug messages, usually used only during project development. By default, the framework settings have a maximum level set below (info), and these messages will not be saved to the log.
info() - informational messages that are necessary to understand how a particular part of the code functions and if all conditions are met. Here you can output a specific SQL query so you can later verify its correct execution.
notice() - notifications about events in the system. For example, it can signal an approach to a critical threshold of some important value that has not yet been reached.
warning() - for logging exceptional cases, not as critical errors, but as warnings. For example, the use of deprecated APIs, misuse of APIs, and other undesirable cases.
error() - runtime errors occurring under certain conditions. These errors do not require immediate action but should be registered and monitored.
critical() - critical errors in the program, such as the unavailability of one of the components.
alert() - general system unavailability, which could be a database failure, entire website downtime, etc. Actions to resolve this should be taken immediately.
emergency() - the system is completely unusable.
#Logging Context
According to PSR-3, you can pass a named array of data as the second argument for substitution in the message text, for example:
In the built-in framework log, you can also add other data to the array, and they will be output by key in the log in the section with 'request-id'. Third-party logging mechanisms may not support this feature.
#Alternative Logger
The HLEB2 framework supports only one active instance of the logging mechanism; if you need to replace it with a third-party logger, this must be done during the framework initialization. This necessity is justified by the fact that error logging should start from the very beginning of loading and operation of the framework itself.
#Logging Settings
In the /config/common.php file:
log.enabled - enables/disables saving to logs, which can be useful when temporarily disabling logging to reduce application load.
max.log.level - sets the maximum logging level (from messages to critical errors).
For example, if you set the level to 'warning', logs with levels 'debug', 'info', and 'notice' will not be saved.
max.cli.log.level - the maximum logging level when using the framework via console commands from the terminal or task scheduler.
error.reporting - this parameter relates to the error level but is also related to logging as it determines which errors will enter the log.
log.sort - for standard file logging, it splits logs by source (site domain).
log.stream - outputs logs to the specified output stream if specified, for example, '/dev/stdout'.
log.format - two formats are available for standard logging, 'row' (default) and 'json', the latter converts log outputs into JSON format.
In the /config/main.php file:
db.log.enabled - logs all queries to the databases.
#Usage Examples
General examples that show the difference between logging errors and regular informational logs:
logger()->info('Info message');
try {
throw new ErrorException('Warning message');
} catch(\ErrorException $e) {
// Will output an error to the log and continue execution.
logger()->warning($e);
}
// Will output an error to the log and interrupt execution.
throw new ErrorException('Error message');
#Viewing Logs
With standard file storage of logs, the most recently added logs can be displayed in the terminal using the console command:
$php console --logs 3 5
The specified command will display the last three logs for the five most recent log files by date.
In the log record (by default, in files), each log entry has a "request-id" label, which can be used to filter all logs for a specific request.
For UNIX systems and macOS, you can use the 'grep' command to search by error type:
$grep -m10 :ERROR ./storage/logs/*
This command's flexibility allows searches under various conditions, including by "request-id" of a request.
For Windows, an alternative would be the 'findstr' command:
D:\project>findstr /S /C:":ERROR" "storage/logs/*"
#Log Rotation
The framework includes the App\Commands\RotateLogs class, a console command implementation for deleting outdated log files.
$php console rotate-logs 5
This command will delete all log files created more than five days ago. By default, it is set to three days. The command is intended for manual rotation or to be added to a task scheduler (for daily execution).
To enable the framework to automatically monitor the maximum size of log files, configure the 'max.log.size' option in the /config/common.php file. The value is specified as an integer in megabytes. However, with this setting active, if there is an unexpectedly high log volume within the current day, all logs from the previous day may be deleted.
← Caching Path →