I’m a big fan of doing my WordPress development live and using Xdebug for tracing WordPress’ execution. But, sometimes you need real-time data of what is going on with certain hooks or functions on your site. I recently discovered the app Papertrail which does just that.
Though there are several, similar web apps out there, I chose Papertrail for two reasons: The first is because it has a free option. The second reason is because Scott Kingsley Clark wrote an easy-to-use API client for Papertrail as a WordPress plugin.
In this article, I’m going to show you how to use Papertrail to log errors or other events on your WordPress site. Once implemented, you will be able to see when certain hooks run, errors are created, or other events you choose occur.
Before You Start
The first thing you will need is a Papertrail account. Once you are signed up, copy the URL for your destination. You can find that URL here: https://papertrailapp.com/account/destinations.
Once you have that destination copied, go to your wp-config file and set it as the value of a constant called WP_PAPERTRAIL_DESTINATION.
Then you need to install and activate the WP_PaperTrail plugin. You can download it from GitHub: https://github.com/sc0ttkclark/papertrail.
Logging Events
Now that you’re all set up, you can begin logging events.
The WP_Papertrail plugin has one class, “WP_Papertrail_API.” This class has a method called “log,” which is how you send events to Papertrail. This function accepts two parameters.
The first parameter is an array or an object, which will be JSON encoded and sent to Papertail. The second parameter is the event name. This parameter is optional, but I highly recommend you use it. The Papertrail UI turns the event names into links, letting you easily view all events of the same name.
I will now show a few uses for this system.
Logging When A Hook Fires
Sometimes it’s useful to see the order of certain hooks firing or if they fire at all. For this, I made a generic callback function I can hook to any action or filter to send the hook name and its first parameter.
function slug_log_hook( $arg ){
if( class_exists( 'WP_Papertrail_API' ) ){
WP_Papertrail_API::log( [
'arg' => $arg
], current_filter() );
}
return $arg;
}
Just hook this to any action or filter to track the time it runs. Notice that I am returning the first argument so this can be safely used with filters.
Tracking Orders
Some hooks need special handling. For example, I set the app up to tell me the ID of every WooCommerce order when they the order is completed. To do this, I hooked into the “woocommerce_order_status_complete” filter.
add_filter( 'woocommerce_order_status_completed', function( $order_id ){
if( class_exists( 'WP_Papertrail_API' ) ){
WP_Papertrail_API::log( [ 'order-id' => $order_id ], 'new_order' );
}
return $order_id;
});
You could even send the full order details using WC_API_Orders::get_order(), like this:
add_filter( 'woocommerce_order_status_completed', function( $order_id ){
if( class_exists( 'WP_Papertrail_API' ) ){
WP_Papertrail_API::log(
[
'details' => WC_API_Orders::get_order( $order_id ),
'order-id' => $order_id
], 'new_order' );
}
return $order_id;
});
Tracking Emails
You can also see when emails are sent and who they are sent to. Using the “wp_mail” filter, record details from the emails that WordPress is trying to send. In addition, you can use wp_mail_failed to track email failures.
Here is how I record emails being sent:
add_action( 'wp_mail', function( $args ){
if( class_exists( 'WP_Papertrail_API' ) ){
WP_Papertrail_API::log( [
'to' => $args[ 'to' ],
'subject' => $args[ 'subject' ],
], 'wp_mail' );
}
});
And here is how I track email failures:
/**
* Log email fails
*/
add_action( 'wp_mail_failed', function( $error ){
if( class_exists( 'WP_Papertrail_API' ) ){
WP_Papertrail_API::log( $error, 'wp_mail_failed' );
}
});
Logging Anything
Here is one more example of using Papertrail for logging errors. In this example, I created a very simple function that makes a GET request to a remote API using the WordPress HTTP API. That function throws an exception if the request returns an error. In the implementation below, that exception is caught with the error and url sent to Papertrail:
function slug_make_request( $api ){
$r = wp_remote_request( $api );
if( is_wp_error( $r ) ){
throw new Exception( $r->get_error_message() );
}
return wp_remote_retrieve_body( $r );
}
try {
$url = 'http://somurl.com/wp-json';
$response = slug_make_request( $url );
} catch (Exception $e) {
if( class_exists( 'WP_Papertrail_API' ) ){
WP_Papertrail_API::log( [
'error' => $e->getMessage(),
'url' => $url
], 'api_request_failed' );
}
}
These are just a few of the things you can log using Papertrail. Feel free to go out and find some more of your own. Just be careful not to overuse and become bogged down with data.
Start Logging
Papertrail is an extremely useful application and is very user-friendly. Being able to watch a live site execute various tasks has been very helpful for me. It’s especially useful for watching background tasks that run on wp-cron.
I hope that by reading this article you have found some use for a real-time logging system and will be able to utilize this on your own site. For now, it is the best option out there.
On a similar note, I recently attended a talk at WPCampus by Roy Sivan in which he showed how to build real-time apps using WordPress and Firebase. You can see his slides here and watch the video of the talk. It’s also a topic he has covered here on Torque. This made me strongly consider building my own, similar system. So far I have resisted the urge, but who knows.
No Comments