Drupal 8 Module of the Week: Monolog

Special PHP-Interoperability Edition! Each day, more Drupal 7 modules are being migrated over to Drupal 8 and new ones are being created for the Drupal community’s latest major release. In this series, the Acquia Developer Center is profiling some of the most most prominent, useful modules, projects, and tools available for Drupal 8. This week, logging with Monolog.

I spoke with Luca Lusso, Paris Liakos (lussoluca and parisliakos on Drupal.org) about the Drupal integration of Monolog, the most popular PHP logging solution and some of the benefits it can bring to your site above and beyond Drupal’s standard logging. And since Drupal 8 is the first major “meta-project” taking advantage of the PHP-interoperability era, I thought I’d get some perspective on Monolog from its creator, Jordi Boggiano. Jordi is also the maintainer of Composer, PHP’s dependency management solution and one of the main enablers of all the interoperability going on in PHP Land.

What does the Monolog Module do?

The Drupal Monolog Module extends what you can do with logging by integrating Drupal with the very popular Monolog PHP logging library. Very popular you say? Yes! It has more than 27 million reported installs (!) and comes bundled with Symfony, Laravel and a number of other frameworks. Luca outlines the basics, “Monolog abstracts how a log message is written to a logging backend. It can send logs to files, sockets, inboxes, databases and various web services.” Monolog gives you fully configurable logging, allowing you to define logging levels, actions, and responses to various potential situations in your application. Jordi continues, “In a nutshell, it lets you describe a logging pipeline. Then when it logs something, it dispatches it along that pipeline to whichever files, services, emails, etc. that you defined.”

Why is this important?

Drupal core logging is a relatively minimal solution, allowing developers to define a log message type, “attention level,” and then save all log messages to a destination--usually Syslog, but the logging can be redirected to another destination. All the log messages are handled the same way, kept in the same place, and critical problems are listed together with (often buried in) trivial logged information. Drupal core logging doesn’t allow you, for example, to save that trivial information in the database, but send critical log-levels or -types somewhere else.

“When an unexpected problem hits one of our sites,” Luca explains, “we or the site owners need to know what happened to cause it.” Was it connected to content or configuration? Did a user perform a particular action? Was a node created or deleted? “All of this information is written to the log system by Drupal but it can be quickly replaced with newer log messages on an active site. And the messages can be difficult to recover because they all stay in the same log stream along with PHP errors and warnings and all the other types of system logs.”

Monolog allows you to set up solutions like sending critical logs to email (or a Slack instance, or HipChat, or NewRelic, or a whole bunch of interesting other options), normal logs to a persistent backend like Logstash, and info/debug to a simple log file of a pre-defined, limited size. Luca talks about the benefit of this system when working for clients, “This separation of information by concerns dramatically improves our access to the specific log information that is important to us in any given situation. It also helps us get notified--wherever we want--the moment there’s a critical problem on a client site.”

Luca shows how Monolog can enhance the working relationship with your clients: You can set up your Drupal site with Monolog to write CMS logs (operations on content, user actions) to a specific stream, so “a site owner and businesses can access that information quickly and without the burden of all the other log messages. On the other hand, a system administrator can see all system logs on a different stream, and maybe receive critical messages only via email (or Slack, or whatever).”

“There’s this joke,” Jordi pulls out an old chestnut,” that a developer's job is just to write bugs all day. There is some truth to that, most somewhat-complex software eventually goes wrong due to unforeseen conditions. Logging can help you greatly with debugging as it surfaces errors and can also provide context that reduces the time you need to fix those bugs.” Monolog adds greatly to the level of context available to you about your log information.

log output

When was Monolog created?

“Around five years ago, we needed a logging system that was flexible enough for Symfony2,” In the best open source tradition, Jordi understood that “having it standalone meant that others could quickly jump in and use it,” help improve it, and so on. “With the advent of PSR-3,” the Logger Interface Standard, for which Jordi was the editor and a major driving force, “we even ended up with a standard, so you can now use Monolog without depending on it directly.”

How did Drupal 8 change the Monolog Module?

services xml file

Luca gives some insight on the Drupal side of the story: “Monolog for Drupal 7 was created by Chris Pliakas and sponsored by Acquia. Now Paris Liakos has taken over maintainership. When the module was created, it wasn’t easy to integrate an external library because the Drupal autoloader didn’t support class namespaces ... or simply because we didn’t have a service container (without using some other contrib modules).”

“In Drupal 8, the Logger component is a Symfony service with a PSR-3 compliant interface and adding an external PHP library now is pretty easy (with modules like Composer manager or directly with Composer itself). The Monolog module for Drupal 8 leverages the new system-architecture to provide a better integration in fewer lines of code.”

“We chose to keep the code as simple as possible and for this reason, the Drupal 8 version doesn’t have a user interface. Sometimes it’s just better to do configuration in code. We explain this in more detail on our WellNet blog, Logging in Drupal 8.”

“Developing for Drupal 8 presents some interesting new challenges. The first version of this module used the plugin system, then we switched to configured services for simplicity and efficiency. So Drupal 8 introduced two ways of doing things, the Drupal one (hooks, plugins, ...) and the Symfony one (services, events, ...). Choosing between the two is sometimes difficult for newcomers.”

Monolog for all my people ... er ... Libraries!

One aspect of the new world of PHP interoperability that Jordi feels is often overlooked is that, “With PSR-3 any library can optionally accept a logger instance. For example, in this line of the Composer ca-bundle (see image below), if you provide a logger we will log some debug info and warnings. This can prove helpful in understanding what is going on when things go wrong without having to litter the code with var_dump.” :-)

"Now since this code uses PSR-3, you could ship Drupal or your Drupal application with Monolog or any other PSR-3-compliant logger. You can just pass it in the library and you instantly get valuable logging information back from that library, for free. I wish more libraries would accept optional loggers, I think it could be quite beneficial in many cases."

optional logger instance code in Composer ca-bundle

More info on Monolog - Links / References