How to Log Messages in Drupal 8

Image

Note: For related topics to this tutorial that you may need to understand, you may be interested in tutorials about using dependency injection, which is needed to get the logger service into your code. Understand the Service Container and Get a Service from the Container are good places to start with that. Additionally the Entity API Hooks tutorial uses logging as an example when working with entities.

Developers familiar with Drupal 7 will also be familiar with watchdog(), an API function that allows you to create a log message that appears on the Reports page in the Drupal administrative UI. Implementing D7’s hook_watchdog allows module developers to customize the destination of these log messages. In Drupal 8, both functions are replaced by a PSR-3-compatible logging interface (change notice).

In this tutorial, you’ll learn how to create the D8 equivalent of D7’s watchdog() function: creating a log message that appears on the Reports administrative page. In a future tutorial, we’ll cover how to create your own logger, and use it in your custom module. However, I've left you some hints and pointers at the end of this tutorial if you care to dive in before then.

Before and after

There is a straight-up D8 procedural equivalent of D7’s watchdog function, as we learn from the change notice:

Drupal 7 watchdog()

<?php
// Logs a notice
watchdog('my_module', $message, array());
// Logs an error
watchdog('my_module', $message, array(), WATCHDOG_ERROR);
?>

Drupal 8 logger class

<?php
// Logs a notice
\Drupal::logger('my_module')->notice($message);
// Logs an error
\Drupal::logger('my_module')->error($message);
?>

Learn from Examples

I downloaded the Examples for Developers module (version 8.x-1.x, but please consult the project page for the latest version) and looked for an example of this in action. I found a good one in the content_entity_example module within the Examples project.

After downloading Examples, open the project in your code editor or IDE of choice. (With Drupal 8’s object-oriented framework, I highly recommend using an IDE such as PhpStorm, simply because it makes navigating classes, methods, and their implementations so much easier.

Let’s take a look at the ContactDeleteForm class in examples/content_entity_example.

In your code editor, navigate to:

examples/content_entity_example/src/Form/ContactDeleteForm.php

If you have Examples downloaded to a Drupal 8 installation, that path is:

DRUPALROOT/modules/examples/content_entity_example/src/Form/ContactDeleteForm.php

In the submitform() method, we see the following:

public function submitForm(array &$form, FormStateInterface $form_state) {
    $entity = $this->getEntity();
    $entity->delete();

    \Drupal::logger('content_entity_example')->notice('@type: deleted %title.',
        array(
            '@type' => $this->entity->bundle(),
            '%title' => $this->entity->label(),
        ));
    $form_state->setRedirect('entity.content_entity_example_contact.collection');
}

Let’s break this down.

Image

a. \Drupal::

In this example, the submitForm method relies on the Drupal service container wrapper, a class which smooths the transition from procedural to object-oriented code in the Drupal code base. The double colon means that we’re accessing a class from “elsewhere,” or outside of the class that it’s called from. It’s kind of like using an absolute path instead of relative one.

b. logger

A helper method that quickly creates a copy of the logger service.

In core/lib/Drupal.php, we find:

public static function logger($channel) {
    return static::getContainer()->get('logger.factory')->get($channel);
  }

So, from this, it looks like the logger method is way to kick-start the logger factory and get a copy of the logger to use in our code.

c. module name

The name of the module, in this case “content_entity_example.”

d. severity-level method

The name of the method in the \Drupal::logger service (in this case “alert”), which will correspond to a severity level, i.e. debug, info, notice, warning, error, critical, alert, emergency. These can be also found in the \PSR\Log\LoggerInterface in the file DRUPALROOT/vendor/psr/log/Psr/Log/LoggerInterface.php

e. log message

This can be a simple quoted PHP string, or a string that utilizes placeholders. In the latter case, pass in an associative array of specially formatted placeholder keys and values into the second parameter.

f. placeholders (array)

An array of placeholder keys and values. The key is the placeholder name with the appropriate prefix (see below for explanation), and the value is what should be used as a value. In this case, a method is called that supplies the value. Placeholders are provided so that values from context may be provided in the message. The logger will transform any placeholder messages to a safe format for output to HTML. For more information, see:

• public function LogMessageParserInterface::parseMessagePlaceholders
• public static function SafeMarkup::format
• protected static function FormattableMarkup::placeholderFormat

Placeholder types

@variable — Use this style of placeholder for most use-cases. Special characters in the text will be converted to HTML entities.

%variable — Use this style of placeholder to pass text through drupal_placeholder() which will result in HTML escaped text, then wrapped with <em> tags.

:variable — Use this style of placeholder when substituting the value of an href attribute. Values will be HTML escaped, and filtered for dangerous protocols.

How to view log messages as administrator

Log messages created with the \Drupal::logger service can be viewed and filtered on the Reports page of the administrative UI. In the Administrative menu, go to Reports > Recent log messages. On this page is a list of recent log messages which you can filter by type and severity.

Image

Why log messages?

Why would you want to use logging in your modules? You know how debug messages are really valuable during development? Well, when a site is in production and debug messages are no longer an option on a public site, log messages are a way to keep tabs on important things that are happening on your site—from notices about users signing in, to major errors that signal a problem that needs immediate attention. They can help you troubleshoot problems and find errors—both large and small—that need attention.

What should I be logging?

You can and should log anything that will help you keep tabs on what your users are doing, how the system is performing, and behind-the-scenes, automatic notifications, which can help you troubleshoot various errors. Things like:

• Actions performed by users
• Recoverable errors
• "Recurly notification processed"

As a developer, visit your Reports page often to learn about notices and recoverable errors that can let you know about places in your code that need attention. They may not be bringing down the system, but they are having some kind of impact and may point to one or more bugs.

Exercise: Implement your own logger

In Drupal 7, you could implement hook_watchdog in your module if you wanted to log messages to custom locations. In Drupal 8, hook_watchdog has been removed, and you now register your logger as a service in your module’s MODULENAME.services.yml, and then in your logger class, implement the \Psr\Log\LoggerInterface and customize the logging destinations as you wish.

Several examples and variations of this can be found in core; for example, in contact, aggregator, and syslog core modules.

In a future tutorial, we’ll walk you through how to implement your own custom logger. For now, start using Drupal 8's logger to create log messages in your fresh new Drupal 8 modules and keep an eye on that Reports page!

Happy logging!