From 07a9c8b3a2ce4bcf8dd3fadf062a9a683af669bf Mon Sep 17 00:00:00 2001
From: Antoine Lamirault <lamiraultantoine@gmail.com>
Date: Sun, 14 Jan 2024 16:35:45 +0100
Subject: [PATCH] Update ElasticsearchLogstashHandler documentation

---
 logging/handlers.rst | 78 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 69 insertions(+), 9 deletions(-)

diff --git a/logging/handlers.rst b/logging/handlers.rst
index 8821113405e..37ad7ca0269 100644
--- 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::
@@ -87,7 +79,10 @@ To use it, declare it as a service:
 
     The ``$elasticsearchVersion`` argument was introduced in Symfony 5.4.
 
-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::
 
@@ -134,4 +129,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