Merge branch '5.4' into 6.3

javiereguiluz · javiereguiluz · commit 2e2ef9830506 · 2024-01-18T11:49:33.000+01:00
* 5.4:
  Update ElasticsearchLogstashHandler documentation
diff --git a/logging/handlers.rst b/logging/handlers.rst
@@ -8,14 +8,6 @@ This handler deals directly with the HTTP interface of Elasticsearch. This means
 it will slow down your application if Elasticsearch takes time to answer. Even
 if all HTTP calls are done asynchronously.
 
-In a development environment, it's fine to keep the default configuration: for
-each log, an HTTP request will be made to push the log to Elasticsearch.
-
-In a production environment, it's highly recommended to wrap this handler in a
-handler with buffering capabilities (like the ``FingersCrossedHandler`` or
-``BufferHandler``) in order to call Elasticsearch only once with a bulk push. For
-even better performance and fault tolerance, a proper `ELK stack`_ is recommended.
-
 To use it, declare it as a service:
 
 .. configuration-block::
@@ -83,7 +75,10 @@ To use it, declare it as a service:
             ])
         ;
 
-Then reference it in the Monolog configuration:
+Then reference it in the Monolog configuration.
+
+In a development environment, it's fine to keep the default configuration: for
+each log, an HTTP request will be made to push the log to Elasticsearch:
 
 .. configuration-block::
 
@@ -130,4 +125,69 @@ Then reference it in the Monolog configuration:
             ;
         };
 
+In a production environment, it's highly recommended to wrap this handler in a
+handler with buffering capabilities (like the `FingersCrossedHandler`_ or
+`BufferHandler`_) in order to call Elasticsearch only once with a bulk push. For
+even better performance and fault tolerance, a proper `ELK stack`_ is recommended.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/prod/monolog.yaml
+        monolog:
+            handlers:
+                main:
+                    type: fingers_crossed
+                    handler: es
+
+                es:
+                    type: service
+                    id: Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler
+
+    .. code-block:: xml
+
+        <!-- config/packages/prod/monolog.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:monolog="http://symfony.com/schema/dic/monolog"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/monolog
+                https://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
+
+            <monolog:config>
+                <monolog:handler
+                    name="main"
+                    type="fingers_crossed"
+                    handler="es"
+                />
+                <monolog:handler
+                    name="es"
+                    type="service"
+                    id="Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler"
+                />
+            </monolog:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/prod/monolog.php
+        use Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler;
+        use Symfony\Config\MonologConfig;
+
+        return static function (MonologConfig $monolog): void {
+            $monolog->handler('main')
+                ->type('fingers_crossed')
+                ->handler('es')
+            ;
+            $monolog->handler('es')
+                ->type('service')
+                ->id(ElasticsearchLogstashHandler::class)
+            ;
+        };
+
+.. _`BufferHandler`: https://github.com/Seldaek/monolog/blob/main/src/Monolog/Handler/BufferHandler.php
 .. _`ELK stack`: https://www.elastic.co/what-is/elk-stack
+.. _`FingersCrossedHandler`: https://github.com/Seldaek/monolog/blob/main/src/Monolog/Handler/FingersCrossedHandler.php
