feature #5137 Added a note about the rotating_file monolog handler (javiereguiluz)

This PR was merged into the 2.3 branch.

Discussion
----------

Added a note about the rotating_file monolog handler

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | all
| Fixed tickets | #1161

Commits
-------

db1e798 Created a new section for rotating log files and explained the max_files configuration option
7345c17 Added XML and PHP configuration samples
31fd0db Added a note about the rotating_file monolog handler

Author: weaverryan

cookbook/logging/monolog.rst

@@ -222,20 +222,76 @@ easily. Your formatter must implement
             ),
         ));
 
+How to Rotate your Log Files
+----------------------------
+
+Beware that log file sizes can grow very rapidly, leading to disk space exhaustion.
+This is specially true in the ``dev`` environment, where a simple request can
+generate hundreds of log lines. Consider using tools like the `logrotate`_
+Linux command to rotate log files before they become a problem.
+
+In case you cannot use a dedicated tool for rotating log files, consider using
+the special ``rotating_file`` handler defined by Monolog. This handler creates
+a new log file every day and can also remove old files automatically. To use
+it, just set the ``type`` option of your handler to ``rotating_file``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/config_dev.yml
+        monolog:
+            handlers:
+                main:
+                    type:  rotating_file
+                    path:  %kernel.logs_dir%/%kernel.environment%.log
+                    level: debug
+                    # max number of log files to keep
+                    # defaults to zero, which means infinite files
+                    max_files: 10
+
+    .. code-block:: xml
+
+        <!-- app/config/config_dev.xml -->
+        <?xml version="1.0" charset="UTF-8" ?>
+        <container xmlns=''http://symfony.com/schema/dic/services"
+            xmlns:monolog="http://symfony.com/schema/dic/monolog">
+
+            <monolog:config>
+                <monolog:handler name="main"
+                    type="rotating_file"
+                    path="%kernel.logs_dir%/%kernel.environment%.log"
+                    level="debug"
+                    <!-- max number of log files to keep
+                         defaults to zero, which means infinite files -->
+                    max_files="10"
+                />
+            </monolog:config>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/config_dev.php
+        $container->loadFromExtension('monolog', array(
+            'handlers' => array(
+                'main' => array(
+                    'type'  => 'rotating_file',
+                    'path'  => '%kernel.logs_dir%/%kernel.environment%.log',
+                    'level' => 'debug',
+                    // max number of log files to keep
+                    // defaults to zero, which means infinite files
+                    'max_files' => 10,
+                ),
+            ),
+        ));
+
 Adding some extra Data in the Log Messages
 ------------------------------------------
 
 Monolog allows you to process the record before logging it to add some
 extra data. A processor can be applied for the whole handler stack or
 only for a specific handler.
 
-.. tip::
-
-    Beware that log file sizes can grow very rapidly, leading to disk space exhaustion.
-    This is specially true in the ``dev`` environment, where a simple request can
-    generate hundreds of log lines. Consider using tools like the `logrotate`_
-    Linux command to rotate log files before they become a problem.
-
 A processor is simply a callable receiving the record as its first argument.
 Processors are configured using the ``monolog.processor`` DIC tag. See the
 :ref:`reference about it <dic_tags-monolog-processor>`.