Need extended information on Logging

[astorm]

Original Ticket Suggestion

Suggestion for http://devdocs.magento.com/guides/v2.0/howdoi/bk-how-do-i.html

How do module developers log a message to system.log when creating their own modules?
How do module developers log a message to a custom log file?

Existing content in DevDocs

https://devdocs.magento.com/guides/v2.2/config-guide/log/log-intro.html
https://devdocs.magento.com/guides/v2.2/config-guide/log/log-magento.html
https://devdocs.magento.com/guides/v2.2/config-guide/log/log-db.html

Need more information!

Read through the comments for ideas and deeper technical information we could use in these topics!

What do you think about this? If it's suitable we'll turn it into a How Do I topic.

[astorm]

@xcomSteveJohnson Yup, that's a good template to use for a dev docs argument, and the sort of thing I was thinking about.

Thank you. Created internal issue MAGETWO-47820 to track

@astorm Let us know what you think: http://bit.ly/29xO5Hd

[astorm]

A good first draft, but it doesn't go far enough.

You mention

Log to files and syslog, Send alerts and e-mails, Log specific servers and networked logging, Logging in development (integration with FireBug and ChromePHP, among others), Log to the database

However, I don't see any concrete example of how this works. i.e. you say you can log to files, but the three articles don't show which files get logged to. Some like like

1. Write this code
2. Run this code
3. Look in file x on your system for the message

It's also not clear from the above if Magento has stock loggers for logging to email, Chrome, etc, or if you're just pointing out one could implement something like this themselves.

[mttjohnson]

Agreed. It is a nice first draft, but does lack a lot of details for understanding how to utilize a logger affectively.

There are two handlers currently defined in the Magento di.xml that will write to the /var/log/debug.log and /var/log/system.log.

<type name="Magento\Framework\Logger\Monolog">
    <arguments>
        <argument name="name" xsi:type="string">main</argument>
        <argument name="handlers"  xsi:type="array">
            <item name="system" xsi:type="object">Magento\Framework\Logger\Handler\System</item>
            <item name="debug" xsi:type="object">Magento\Framework\Logger\Handler\Debug</item>
        </argument>
    </arguments>
</type>

The way Monolog works is that it has the capability to "bubble" a message from one handler on to the next one in the list if the handler allows the record to be bubbled. When the System handler's constructor is called when instantiated it will build a handler that isHandling() any records that have a level >= Logger::INFO. Any records that the Logger addRecord() receives will get evaluated to see if the handlers in the list will handle them or not.

So in instances of using $this->logger->critical($e) like your example, the Logger addRecord() method would check to see which handlers in the list are able to handle the record, and because the System handler would accept handling a critical record (Logger::CRITICAL) the System handler will process the write for the record and one would expect it to write to the /var/log/system.log file, but that's not what happens. The Magento\Framework\Logger does some checking of the message (record) that it gets in it's addRecord() method and if it happens to be an instance of \Exception as in your example it will set the $context['is_exception'] variable to true and when the System handler goes to write the record, the System handler will see that $record['context']['is_exception'] is true and decide not to write itself and instead pass the record over to a different handler, the Exception handler. The Exception handler then writes to the /var/log/exception.log file.

If you are going to make a few examples, I'd suggest doing some $this->logger->debug("hello world") and $this->logger->critical("hello world") examples in addition to your exception so that you can demonstrate which ones get written to the three common log files exception.log, system.log and debug.log.

As far as extending the capabilities of Monolog for the other ways you can use logging, like you hint at in logging to a database, you may find that providing an example of that is a bit more difficult because that kind of capability would be provided by additional handlers. There are some fundamental issues with adding any additional handlers to the Magento\Framework\Logger\Monolog see Magento 2 Issue #2529. Aside from any architectural concerns, there is a bug in the version of Monolog that Magento 2 is currently using that prevents any bubbling of messages to any successive handlers, and only the first handler in the list of handlers that accept the record is getting called.

I implemented a separate Monolog file handler and database handler, but wasn't able to find a way to utilize the Magento Logger, so I ended up writing my own Logger and injecting it instead of the \Psr\Logger\LoggerInterface and I wasn't happy with the solution I came up with. If you want to see an implementation of using a handler to write to the database, or change how things are written to a separate log file, you could see some implementations here, but I don't know how you'd want to go about demonstrating the use of that while using the Magento Logger.

@mttjohnson Thanks for your input. We'll keep you posted.

[astorm]

Any update on is, or is this not going to happen?

I'm waiting on input from engineering. I don't have an ETA for that.

[astorm]

Thanks for the update @xcomSteveJohnson -- we live in hope :)