php symfony dependency-injection monolog

how are channels defined in symfony monolog?

I've spent several hours going over the monolog documentation.. and I just couldn't figure out this basic question: how are channels defined in monolog? I got this symfony2 project that has this in the config.yml file:

monolog:
    handlers:
        api:
            type:  stream
            path:  "%kernel.logs_dir%/%kernel.environment%_api_request_raw.log"
            channels: api
            formatter: monolog.formatter.session_api
        api_low:
            type:  stream
            path:  "%kernel.logs_dir%/%kernel.environment%_api_request_low.log"
            channels: api_low
            formatter: monolog.formatter.session_api
        car_location:
            type:  stream
            path:  "%kernel.logs_dir%/car locations/%kernel.environment%_carLocation_not-recognized.log"
            channels: not_recognized
            level: %log_debug_level%
            formatter: monolog.formatter.session_location
        active_request:
            type:  stream
            path:  "%kernel.logs_dir%/%kernel.environment%_api_active_request.log"
            channels: active_request
            level: %log_debug_level%
            formatter: monolog.formatter.session_location
        get_request:
            type:  stream
            path:  "%kernel.logs_dir%/%kernel.environment%_api_get_request.log"
            channels: get_request
            level: %log_debug_level%
            formatter: monolog.formatter.session_location

now in the same file under services I got these:

services:
    monolog.formatter.session_location:
        class: Monolog\Formatter\LineFormatter
        arguments:
            - "[%%datetime%%] %%level_name%%: %%message%%\n"

    monolog.formatter.session_api:
        class: Monolog\Formatter\LineFormatter
        arguments:
            - "[%%datetime%%] %%channel%%.%%level_name%%: %%message%%\n"

which basically customizes the log message.. fair enough..

the part I don't understand is that what does api_low mean? where is it defined? how is api_low different than api? I see here for example that the handler name is the same as the channel (ie api handler has an api channel).. but i don't know what to make of it

If i simply put a

 $logger = $this->get("logger");
 $logger->debug("hello world");

in my code i get this log in the console:

[2014-05-16 15:38:15] app.DEBUG: hello world [] []

I also see these in the console as well:

[2014-05-16 15:38:08] request.INFO: Matched route "sonata_admin_dashboard" (parameters: "_controller": "St\AdminBundle\Controller\DashboardController::dashboardAction", "_route": "sonata_admin_dashboard") [] []
[2014-05-16 15:38:08] event.DEBUG: Notified event "kernel.request" to listener "Symfony\Component\HttpKernel\EventListener\LocaleListener::onKernelRequest". [] []
[2014-05-16 15:38:08] event.DEBUG: Notified event "kernel.request" to listener "Symfony\Component\Security\Http\Firewall::onKernelRequest". [] []
[2014-05-16 15:38:08] security.DEBUG: Read SecurityContext from the session [] []
[2014-05-16 15:38:08] security.DEBUG: Reloading user from user provider. [] []
[2014-05-16 15:38:08] doctrine.INFO: MongoDB query: {"find":true,"query":{"_id":{"$id":"51c8c071efe5b8dd09000003"},"type":{"$in":["user","client","partner"]}},"fields":[],"db":"smarttaxi_dev","collection":"User"} [] []
[2014-05-16 15:38:08] doctrine.INFO: MongoDB query: {"limit":true,"limitNum":1,"query":{"_id":{"$id":"51c8c071efe5b8dd09000003"},"type":{"$in":["user","client","partner"]}},"fields":[]} [] []
[2014-05-16 15:38:08] doctrine.INFO: MongoDB query: {"limit":true,"limitNum":1,"query":{"_id":{"$id":"51c8c071efe5b8dd09000003"},"type":{"$in":["user","client","partner"]}},"fields":[]} [] []
[2014-05-16 15:38:08] doctrine.INFO: MongoDB query: {"limit":true,"limitNum":1,"query":{"_id":{"$id":"51c8c071efe5b8dd09000003"},"type":{"$in":["user","client","partner"]}},"fields":[]} [] []
[2014-05-16 15:38:08] security.DEBUG: Username "aiia" was reloaded from user provider. [] []
[2014-05-16 15:38:08] event.DEBUG: Notified event "kernel.request" to listener "FOS\RestBundle\EventListener\BodyListener::onKernelRequest". [] []
[2014-05-16 15:38:08] event.DEBUG: Notified event "kernel

some of them are obvious: doctrine matches related stuff, but i just don't know where i find a definition or a reference for these things.

asked another way: is api_low a monolog defined special key? if so where is the documentation for it? I couldn't find any instance of this string in all the code so i'm assuming it's a predefined variable right?

Solution

No, api_low is not a special key, it's a developer-defined key, to separate the logs (and potentially manage them in different ways, e.g. in different *.log files).

See Cookbook about Monolog and How to use a custom channel in a service for more details.

[EDIT : example]

I assume that:

config.yml is as discribed in your original post
you have a service called MyService which has a function doSomeStuff()
you are familiar with Symfony's services concept

In service.yml:

myService.doSomeStuff:
        class: MyProject\MyBundle\Service\MyService
        arguments: [ "@logger"]
        tags:
            - { name: monolog.logger, channel: api_low }

In MyService.php:

protected $apiLowLogger;    

public function __construct($apiLowLogger)
{
    $this->apiLowLogger = $apiLowLogger;
}

public function doSomeStuff()
{
    $this->apiLowLogger->debug('This debug message will be written in %kernel.logs_dir%/%kernel.environment%_api_request_low.log');
}

To know the different type of logs (debug(), error(), info(), etc.), see the source (permalink).