chore (logging): add stop_buffering config option (#44071)

Adding the stop_buffering config option.

The FingersCrossedHandler Logger will first start buffering log records until a record exceeds the configured action_level. When the action_level is exceeded the buffered records will be flushed to the provided log location.

By default the FingersCrossedHandler will stop buffering log records after its first flush (due to the $stopBuffering property). All records pushed to the log handler afterwards will be flushed directly to the log location.

With this config update the log handler can be configured to resume the buffering after a flush occurs.

This can be useful for applications that rely heavily on gather debug log records which only are useful when an error logging is passed. In the old setup all the debug records after an error record would be flushed to the log location.

@see https://github.com/Seldaek/monolog/blob/main/src/Monolog/Handler/FingersCrossedHandler.php#L73

Co-authored-by: Wim Ulkeman <[email protected]>

Author: wimulkeman

src/Illuminate/Log/LogManager.php

@@ -417,7 +417,13 @@ protected function prepareHandlers(array $handlers)
     protected function prepareHandler(HandlerInterface $handler, array $config = [])
     {
         if (isset($config['action_level'])) {
-            $handler = new FingersCrossedHandler($handler, $this->actionLevel($config));
+            $handler = new FingersCrossedHandler(
+                $handler,
+                $this->actionLevel($config),
+                0,
+                true,
+                $config['stop_buffering'] ?? true
+            );
         }
 
         if (! $handler instanceof FormattableHandlerInterface) {

tests/Log/LogManagerTest.php

@@ -496,6 +496,67 @@ public function testWrappingHandlerInFingersCrossedWhenActionLevelIsUsed()
         $this->assertEquals(Monolog::DEBUG, $expectedStreamHandler->getLevel());
     }
 
+    public function testFingersCrossedHandlerStopsRecordBufferingAfterFirstFlushByDefault()
+    {
+        $config = $this->app['config'];
+
+        $config->set('logging.channels.fingerscrossed', [
+            'driver' => 'monolog',
+            'handler' => StreamHandler::class,
+            'level' => 'debug',
+            'action_level' => 'critical',
+            'with' => [
+                'stream' => 'php://stderr',
+                'bubble' => false,
+            ],
+        ]);
+
+        $manager = new LogManager($this->app);
+
+        // create logger with handler specified from configuration
+        $logger = $manager->channel('fingerscrossed');
+        $handlers = $logger->getLogger()->getHandlers();
+
+        $expectedFingersCrossedHandler = $handlers[0];
+
+        $stopBufferingProp = new ReflectionProperty(get_class($expectedFingersCrossedHandler), 'stopBuffering');
+        $stopBufferingProp->setAccessible(true);
+        $stopBufferingValue = $stopBufferingProp->getValue($expectedFingersCrossedHandler);
+
+        $this->assertTrue($stopBufferingValue);
+    }
+
+    public function testFingersCrossedHandlerCanBeConfiguredToResumeBufferingAfterFlushing()
+    {
+        $config = $this->app['config'];
+
+        $config->set('logging.channels.fingerscrossed', [
+            'driver' => 'monolog',
+            'handler' => StreamHandler::class,
+            'level' => 'debug',
+            'action_level' => 'critical',
+            'stop_buffering' => false,
+            'with' => [
+                'stream' => 'php://stderr',
+                'bubble' => false,
+            ],
+        ]);
+
+        $manager = new LogManager($this->app);
+
+        // create logger with handler specified from configuration
+        $logger = $manager->channel('fingerscrossed');
+        $handlers = $logger->getLogger()->getHandlers();
+
+        $expectedFingersCrossedHandler = $handlers[0];
+
+        $stopBufferingProp = new ReflectionProperty(get_class($expectedFingersCrossedHandler), 'stopBuffering');
+        $stopBufferingProp->setAccessible(true);
+        $stopBufferingValue = $stopBufferingProp->getValue($expectedFingersCrossedHandler);
+
+        $this->assertFalse($stopBufferingValue);
+    }
+
     public function testItSharesContextWithAlreadyResolvedChannels()
     {
         $manager = new LogManager($this->app);