feature #4604 Making the channel handler more useful by showing it on the prod environment (weaverryan)

This PR was merged into the 2.3 branch.

Discussion
----------

Making the channel handler more useful by showing it on the prod environment

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | 2.3+
| Fixed tickets | n/a

Hi guys!

I realized there were a few practical problems with this:

1) Normally, there is no `monolog` configuration in `config.yml` - so it's odd to show an example there
2) In the `prod` environment (by default, unless you set doctrine's logging explicitly to true), the `doctrine` channel is not logged at all. So, if you tried this example in `config_prod.yml`, it probably wouldn't work. But security is always there.

Thanks!

P.S. After merging to 2.6, `container:debug` should be changed to `debug:container`.

Commits
-------

bc79b21 Adding one more note about why we're in config.yml
78323d8 Changing back to config.yml and fixing some code block mistakes thanks to Wouter
f9f3c3f Making the channel handler more useful by showing it on the prod environment

Author: weaverryan

Diff for: cookbook/logging/channels_handlers.rst

@@ -4,21 +4,29 @@
 How to Log Messages to different Files
 ======================================
 
-The Symfony Standard Edition contains a bunch of channels for logging: ``doctrine``,
-``event``, ``security`` and ``request``. Each channel corresponds to a logger
-service (``monolog.logger.XXX``) in the container and is injected to the
-concerned service. The purpose of channels is to be able to organize different
-types of log messages.
+The Symfony Framework organizes log messages into channels. By default, there
+are several channels, including ``doctrine``, ``event``, ``security``, ``request``
+and more. The channel is printed in the log message and can also be used
+to direct different channels to different places/files.
 
 By default, Symfony logs every message into a single file (regardless of
 the channel).
 
+.. note::
+
+    Each channel corresponds to a logger service (``monolog.logger.XXX``)
+    in the container (use the ``container:debug`` command to see a full list)
+    and those are injected into different services.
+
+.. _logging-channel-handler:
+
 Switching a Channel to a different Handler
 ------------------------------------------
 
-Now, suppose you want to log the ``doctrine`` channel to a different file.
-
-To do so, just create a new handler and configure it like this:
+Now, suppose you want to log the ``security`` channel to a different file.
+To do this, just create a new handler and configure it to log only messages
+from the ``security`` channel. You might add this in ``config.yml`` to log
+in all environments, or just ``config_prod.yml`` to happen only in ``prod``:
 
 .. configuration-block::
 
@@ -27,14 +35,17 @@ To do so, just create a new handler and configure it like this:
         # app/config/config.yml
         monolog:
             handlers:
-                main:
-                    type:     stream
-                    path:     /var/log/symfony.log
-                    channels: ["!doctrine"]
-                doctrine:
+                security:
+                    # log all messages (since debug is the lowest level)
+                    level:    debug
                     type:     stream
-                    path:     /var/log/doctrine.log
-                    channels: [doctrine]
+                    path:     "%kernel.logs_dir%/security.log"
+                    channels: [security]
+
+                # an example of *not* logging security channel messages for this handler
+                main:
+                    # ...
+                    # channels: ["!security"]
 
     .. code-block:: xml
 
@@ -48,15 +59,16 @@ To do so, just create a new handler and configure it like this:
                 http://symfony.com/schema/dic/monolog/monolog-1.0.xsd"
         >
             <monolog:config>
-                <monolog:handler name="main" type="stream" path="/var/log/symfony.log">
+                <monolog:handler name="security" type="stream" path="%kernel.logs_dir%/security.log">
                     <monolog:channels>
-                        <monolog:channel>!doctrine</monolog:channel>
+                        <monolog:channel>security</monolog:channel>
                     </monolog:channels>
                 </monolog:handler>
 
-                <monolog:handler name="doctrine" type="stream" path="/var/log/doctrine.log">
+                <monolog:handler name="main" type="stream" path="%kernel.logs_dir%/main.log">
+                    <!-- ... -->
                     <monolog:channels>
-                        <monolog:channel>doctrine</monolog:channel>
+                        <monolog:channel>!security</monolog:channel>
                     </monolog:channels>
                 </monolog:handler>
             </monolog:config>
@@ -67,18 +79,17 @@ To do so, just create a new handler and configure it like this:
         // app/config/config.php
         $container->loadFromExtension('monolog', array(
             'handlers' => array(
-                'main'     => array(
+                'security' => array(
                     'type'     => 'stream',
-                    'path'     => '/var/log/symfony.log',
+                    'path'     => '%kernel.logs_dir%/security.log',
                     'channels' => array(
-                        '!doctrine',
+                        'security',
                     ),
                 ),
-                'doctrine' => array(
-                    'type'     => 'stream',
-                    'path'     => '/var/log/doctrine.log',
+                'main'     => array(
+                    // ...
                     'channels' => array(
-                        'doctrine',
+                        '!security',
                     ),
                 ),
             ),