Using The WordPress Debug Log

Do you ever make mistakes? I do. The first step to fixing your mistakes is knowing what the mistake is. I can’t solve all of your problems, but I can help fix those that are generated by PHP code on your WordPress site by helping you work with debug logs.

A few weeks ago, when I wrote about customizing your WordPress site’s wp-config.php file, I covered settings for debugging. I covered both how to show errors, and when you might not want to do that. While enabling WP_DEBUG, as I described in that article is important in development, you may have some non-fatal errors and warnings that you can’t avoid for whatever reason that you don’t want to displayed to all of your visitors. Also, there may be errors and warning that you are not aware of as you never triggered them, but your site’s visitors are seeing.

For these reasons, on a live site, its a good idea to leave WP_DEBUG enabled, but to prevent errors from being displayed. In order to see these errors and warnings, you will need to write them to a special log file, so you can review them. In this article I will cover setting up error logging and various ways to view your logs. I will also cover how to write other information to that log, and when you might want to do that.

Logging errors, even when you’re displaying them is still useful as having a record of your errors is often very useful in development. You might not be able to make much sense of an error when it first occurs, but once you have more information from subsequent work, the record in your log may be very useful.

Setting Up

This is a brief review of what I discussed in my wp-config article. If you’ve never edited your site’s wp-config file, or do not know what that is or what a constant is, I recommend reading that article and then coming back to this one.

In order to enable debugging, prevent errors and warnings from being displayed and log errors, you need these three lines in your wp-config:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_DISPLAY', false );
define( 'WP_DEBUG_LOG', true );

It’s important  to note that there is nothing you can do to prevent a fatal error from causing a white screen of death, besides enabling debug display, which will show you a white screen with the error in it.

Viewing Your Debug Log

The actual debug log is saved in a file called debug.log in your site’s content directory. One way to view and clear your log is to access that file directly. That’s not a particularly good way of working, especially if your site is on a remote server. There are plugins that make it easier to work with your debug log, which I will discuss shortly. That said, it’s important to be familiar with this method as if you can’t access the WordPress back-end due to a fatal error, your debug log might hold the clues to understand why.

There are multiple ways to view your debug log from the WordPress backend. My preferred method is using the Log Viewer plugin.  This free plugin gives you two ways to view your debug log, as well as the ability to clear it. When this plugin is active, you can view your log from its admin page, which is accessible from inside of the Tools menu. In addition, if you have the Debug Bar plugin active, which is one of the most useful development tools for WordPress, then you can view your log from a panel of the Debug Bar. I do not recommend having Debug Bar active on a live site, so it is nice to have both options. Both plugins can be installed from the WordPress plugin installer or through the Developer plugin, which is full of useful tools to help improve your development.

Here is what the debug log view looks like:

As you can see, every time WordPress encounters a warning or error, or generates a notice, the error, warning or notice is written to the log, with a time stamp in UTC.

Writing Other Information To The Log

In some cases you might want to write information to the log, even if it’s not technically an error. PHP has a function called error_log, that will print information to the error log for you. By default it does not print and format properly. For this reason, I recommend adding an extra function to your site to handle formatting. It is a wrapper for error_log, that uses print_r() to format arrays and objects properly before logging them. Here is what the function looks like:

if ( ! function_exists('write_log')) {
   function write_log ( $log )  {
      if ( is_array( $log ) || is_object( $log ) ) {
         error_log( print_r( $log, true ) );
      } else {
         error_log( $log );
      }
   }
}

I strongly advise against adding this to your theme’s functions.php, as in that case it will no longer work if you take the common debugging step of switching to the default theme. Instead create a plugin for this function. Doing so simply requires creating a file in your plugin directory, adding a plugin header and this function. The header can be as simple as this:

/*
Plugin Name: Log Error
*/

Once you have this function available to you, it has a variety of uses. Want to know if a specific line of code ever gets called? Use:

write_log( __LINE__ );

You can even use it to gather basic intelligence about your site. For example, want to log when a specific post was viewed and if the user who viewed was logged in? Here’s some simple code to do that:

add_action( 'wp_head', 'slug_log_post_view' );
function slug_log_post_view() {
   //set the ID of the post you want to track here:
   $post_to_track = 42;

   //get the current post's ID & make sure it's a valid ID and it matches our ID
   $id = get_queried_object_id();
   if ( intval( $id ) > 0 && $post_to_track === $id ) {

      //check if current user is logged in and if so get the user ID
      if ( is_user_logged_in() ) {
         $user_id = get_current_user_id();
         $user_id = 'a user with the ID ' . $user_id;
      }
      else{
         $user_id = 'a user that was not logged in.';
      }

      //log the information
      write_log( "The post {$post_to_track} was accessed by {$user_id}" );

   }

}

While this function is no Google Analytics,  it does provide a quick and dirty way to gather intelligence on a specific post. Be sure to set the correct post ID in the variable, $post_to_track. You could even enable this for all posts, by removing the check to see if $post_to_track equals $id. If so, be sure to change last line to use $id, instead of $post_to_track.

All Kids Love Log

I hope this introduction to error logging in WordPress has shown you how to use this often overlooked capability of WordPress to help you debug any issues on your site. Don’t forget that PHP errors are not the only type of errors that you can generate. There are also JavaScript errors, which will show up in your browser’s JavaScript console.

Article thumbnail image by PureSolution / shutterstock.com