diff --git a/logging.rst b/logging.rst index 99c09f3dec5..b31809aac91 100644 --- a/logging.rst +++ b/logging.rst @@ -179,15 +179,75 @@ to write logs using the :phpfunction:`syslog` function: ->level(LogLevel::ERROR); }; -This defines a *stack* of handlers and each handler is called in the order that it's -defined. +This defines a *stack* of handlers, where each handler can define +a ``priority`` (default ``0``) to control its position in the stack. + +Handlers with a higher priority are called earlier, while those with the same priority keep +the order in which they are defined: + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/prod/monolog.yaml + monolog: + handlers: + file_log: + type: stream + path: "%kernel.logs_dir%/%kernel.environment%.log" + + syslog_handler: + type: syslog + priority: 10 # called first + + .. code-block:: xml + + + + + + + + + + + + + + .. code-block:: php + + // config/packages/prod/monolog.php + use Psr\Log\LogLevel; + use Symfony\Config\MonologConfig; + + return static function (MonologConfig $monolog): void { + $monolog->handler('file_log') + ->type('stream') + ->path('%kernel.logs_dir%/%kernel.environment%.log') + ; + + $monolog->handler('syslog_handler') + ->type('syslog') + ->priority(10) // called first + ; + }; .. note:: - If you want to override the ``monolog`` configuration via another config - file, you will need to redefine the entire ``handlers`` stack. The configuration - from the two files cannot be merged because the order matters and a merge does - not allow you to control the order. + When adding handlers in additional configuration files, it's recommended to set + an explicit priority to ensure the desired order. .. _logging-handler-fingers_crossed: