diff --git a/logging.rst b/logging.rst index c54b30f7c0d..876b56a28bf 100644 --- a/logging.rst +++ b/logging.rst @@ -371,6 +371,7 @@ Learn more logging/channels_handlers logging/formatter logging/processors + logging/handlers logging/monolog_exclude_http_codes logging/monolog_console diff --git a/logging/handlers.rst b/logging/handlers.rst new file mode 100644 index 00000000000..9445c98babc --- /dev/null +++ b/logging/handlers.rst @@ -0,0 +1,108 @@ +Handlers +======== + +ElasticsearchLogstashHandler +---------------------------- + +.. versionadded:: 4.4 + + The ``ElasticsearchLogstashHandler`` was introduced in Symfony 4.4. + +This handler deals directly with the HTTP interface of Elasticsearch. This means +it will slow down your application if Elasticsearch takes times 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:: + + .. code-block:: yaml + + # config/services.yaml + services: + Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler: ~ + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + // config/services.php + use App\Logger\SessionRequestProcessor; + use Monolog\Formatter\LineFormatter; + use Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler; + + $container->register(ElasticsearchLogstashHandler::class); + +Then reference it in monolog configuration: + + +.. configuration-block:: + + .. code-block:: yaml + + # config/packages/prod/monolog.yaml + monolog: + handlers: + es: + type: service + id: Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler + + .. code-block:: xml + + + + + + + + + + + .. code-block:: php + + use Symfony\Bridge\Monolog\Handler\ElasticsearchLogstashHandler; + // config/packages/prod/monolog.php + $container->loadFromExtension('monolog', [ + 'handlers' => [ + 'es' => [ + 'type' => 'service', + 'id' => ElasticsearchLogstashHandler::class, + ], + ], + ]); + +.. _`ELK stack`: https://www.elastic.co/what-is/elk-stack