How do I log errors, warn­ings, and info in my plu­g­ins to a Craft log file?

Craft makes it easy for you to add a log file for your plugin. Using the static method PluginClassName::log(). Craft will create a new log file for you in the folder craft/storage/runtime/logs and name it after your plugin using all lowercase letters pluginname.log

Using the Sprout Active plugin as an example, in the most simple form, we would add the following line anywhere we wanted to output a message:

SproutActivePlugin::log('This is it.');

By default, the log() behavior just outputs information, however, our log() function can be refined a bit more if we need with three different log levels:

• LogLevel::Info
• LogLevel::Warning
• LogLevel::Error

To log a warning or an error message, we just need to pass the appropriate LogLevel as the second argument:

// Our default Log Level is Info
SproutActivePlugin::log('Just sharing some information', LogLevel::Info);

// We need to specifically add the second argument for Warnings and Errors
SproutActivePlugin::log('Hey, watch out now!', LogLevel::Warning);
SproutActivePlugin::log('Uh oh.', LogLevel::Error);

We will see the level of the log item appear in our log file:

2014/04/08 00:25:36 [info] [plugin] Just sharing some information
2014/04/08 00:25:36 [warning] [plugin] Hey, watch out now!
2014/04/08 00:25:36 [error] [plugin] Uh oh.

If devMode is not enabled, you will only see log messages for warnings and errors in the logs. If devMode is enabled, you will see all of the messages logged. Additionally, with devMode enabled, Craft also adds a stack trace, which includes a bit more information about the files and methods that were triggered before your item got logged.

If you want a log item to appear regardless of whether devMode is enabled, you can pass true as the third argument to the log() method.

SproutActivePlugin::log('Log this with or without devMode enabled.', LogLevel::Info, true);

If you'd like to see more examples, search for "Craft::log" in the Craft app folder and take a look at how Craft is handling its own log files. Craft's Craft::log() method behaves just like the PluginClassName::log() method.

Watching your log files

There are several ways you can monitor and check your log files.

1. Via the filesystem - Open your file with your favorite text editor from the filesystem. Log files are stored in: craft/storage/runtime/logs.
2. Via the Control Panel - Craft has a hidden Utility section in the control panel. You won't find a link to it, but it's just a segment or two away: http://yourwebsite.com/admin/utils/logs
3. Via the console - A handy way to monitor your log files is using the tail command: tail /path/to/craft/storage/runtime/logs/sproutactiveplugin.log. The tail command will output your log messages to the console while you work.

Deprecating Features in your plugin

If you need to deprecate a feature in one of your plugins that other folks might be using, Craft also has a way to log deprecation errors so that they will appear in the Deprecation Logs page in the Control Panel's hidden Utilities section, located at admin/utils/deprecationerrors.

You can do this using the Deprecation Service.

craft()->deprecator->log($key, $message);

An actual example might look like the following. The key will make sure your message is only logged once in a request, and the message should clearly tell a user reading the message the steps they can take to fix the deprecation error.

craft()->deprecator->log('craft()->sproutActive->oldSchoolFunction()', 'craft()->sproutActive->oldSchoolFunction() has been deprecated. Use craft()->sproutActive->newFunction() instead.');