[4.x] How to register additional log targets files?

[MoritzLost]

I'm trying to figure out how to register additional log files (targets) in Craft 4. I'm writing a custom module for a site and I just want to be able to log errors specific to that module in a dedicated log file (@storage/log/custom-module.log or something similar). In Craft 3 this was simple:

Craft::getLogger()->dispatcher->targets[] = new FileTarget([
    'logFile' => App::parseEnv('@logs') . '/custom-module.log',
    'categories' => ['custom-module']
]);

// used like this
Craft::getLogger()->log($message, Logger::LEVEL_INFO, 'custom-module');

The upgrade guide only mentions that custom log targets should be added via components.log.targets, but I'm struggling to find out how to add a new file target as in the example above. This is what I have so far:

// config/app.php

return [
    'components' => [
        'log' => [
            'targets' => [
                'custom-module' => [
                    'class' => MonologTarget::class,
                    'name' => 'custom-module',
                    'enabled' => false,
                    'extractExceptionTrace' => !App::devMode(),
                    'allowLineBreaks' => App::devMode(),
                    'level' => App::devMode() ? LogLevel::INFO : LogLevel::WARNING,
                    'categories' => 'custom-module',
                ],
            ],
        ],
    ],
];

It's not causing any errors but isn't working either, everything I try to log just ends up in the web.log. No idea if I'm on the right track at all. How can I add a custom log target file and then log to it?

On a broader note, is there any documentation on how to use the new logging component? Should I even use Craft::getLogger() any more? As far as I can tell, Craft itself uses static logging methods on the Craft class (Craft::debug(), Craft::warning() etc), but I can't even find where those are defined … should I be using those?

[mattstein]

We’re working on documentation for custom log targets that should be out shortly—I’ll follow up once they’re live!

[MoritzLost]

That's great, thanks!

[MoritzLost]

@mattstein I was looking for info on custom logs and came back to this discussion – is the documentation for defining custom log targets online already? Couldn't find anything in the docs 🤔

[mattstein]

@MoritzLost The long delay is my fault, sorry. There’s a draft page here that needs to be finished out and published, though I’m not sure who’s in charge of that.

[timkelty]

@MoritzLost Thanks for the nudge, I'll get that published!

[timkelty]

@MoritzLost While we are working up updated the docs for this, here's some quick and dirty examples: https://gist.github.com/timkelty/c0530983c3fb450c15a5f136fb388d3d

For you, it would look something like this:

• First, we use monologTargetConfig to filter out any custom-module messages.
• Then we add a new log target, scoped specifically to custom-module.
  • You can add a traditional Yii file target (first example)
  • …or you can add a Monolog target (second example, recommended)

<?php

use craft\helpers\App;
use Monolog\Formatter\LineFormatter;
use Psr\Log\LogLevel;
use yii\i18n\PhpMessageSource;
use yii\web\HttpException;

return [
    'components' => [
        'log' => [
            'monologTargetConfig' => [
                'except' => [
                    PhpMessageSource::class . ':*',
                    HttpException::class . ':40*',
                    'custom-module'
                ],
            ],
            'targets' => [

                // Add a traditional Yii file target
                [
                    'class' => \yii\log\FileTarget::class,
                    'logFile' => '@storage/logs/custom-module.log',
                    'levels' => App::devMode() ? ['info', 'warning', 'error'] : ['warning', 'error'],
                    'categories' => ['custom-module'],
                ],

                // Add a Monolog target
                [
                    'class' => \craft\log\MonologTarget::class,
                    'name' => 'custom-module',
                    'extractExceptionTrace' => !App::devMode(),
                    'allowLineBreaks' => App::devMode(),
                    'level' => App::devMode() ? LogLevel::INFO : LogLevel::WARNING,
                    'categories' => ['custom-module'],
                ],
            ]
        ],
    ],
];

On a broader note, is there any documentation on how to use the new logging component?

Basic usage hasn't changed. Craft::getLogger()->log($message, Logger::LEVEL_INFO, 'custom-module'); is just the long form of Craft::info($message, 'custom-module').

Alternatively, you can now pass a PsrMessage to those methods, which will let you pass in arbitrary data as the context. Example: https://gist.github.com/timkelty/c0530983c3fb450c15a5f136fb388d3d#file-misc-php

[MoritzLost]

@timkelty Awesome, thanks for the example! I got it to work now (turns out I was passing a string instead of an array for the categories 😒). Also good to know how to exclude the custom category from the custom logs. Thanks for the thorough examples!

By the way, is it possible to configure the custom monolog target not to include the Request context for every logged message? It's super verbose and leaks a lot of sensitive information as well …

Nevermind, figured it out, in the components.log.targets config:

                [
                    'class' => \craft\log\MonologTarget::class,
                    'name' => 'custom-module',
                    'categories' => ['custom-module'],
                    'logContext' => false,
                ],

[AugustMiller]

There is a (relatively) new Logging page in the documentation, with a section dedicated to adding targets!