wp2syslog documentation of wp2syslog for plugin developers

wp2syslog is a global event logging facility for WordPress. This document describes how wp2syslog can be used with your code (WP plugins or themes).

Benefits

Developers can benefit in two ways from wp2syslog:

• At each point of the code, a log entry can be triggered. No need to print to the browser, just let wp2syslog put it in the database, and you can have a look later.
• You can develop your plugins with support for wp2syslog. This will give your users the chance to better understand what your plugin is doing.

End users can benefit from wp2syslog, too:

• Log entries for core events help to keep track of the daily business, especially on multiuser blogs.
• Log entries for core events can raise awareness for threats and problems, for example abuse attempts.
• Log entries triggered by plugins allow the user to comprehend the functionality of the plugin.

Integration

Note: The terms must, should, can are used as commonly understood in specifications. In short: must is a prequisite, should is a recommendation, can is an option.

wp2syslog saves log entries in an own database. The central function is wp2syslog() (arguments are described below):

bool wp2syslog($module, $message, $severity=1, $cut=500 $userid=0, $time=0)

In order to trigger log entries, you can place the following line in your code, wherever and as often as you want:

if (function_exists('wp2syslog')) wp2syslog(arguments);

or, if outside of PHP tags:

<?php if (function_exists('wp2syslog')) wp2syslog(arguments); ?>

When the plugin is activated, and the according section is executed, wp2syslog() will create an entry in the log database. The function will return boolean true if it succeeded creating the entry, and boolean false elsewise.

Data format

The function wp2syslog() accepts the followning arguments:

$module

The module must designate your entity (plugin or theme). It must not contain other caracters than lowercase letters, numbers, underscores. It must not be longer than 30 characters. The descriptors core and wp2syslog are reserved.

$message

The message contains a free text to describe the entry. It can be up to 500 characters of any kind. Inline HTML elements can, but should not be used; block HTML elements must not be used. The wording and eventual HTML must be sober and factual, and they must enable the recipient to properly investigate the problem. The message should consist of complete sentences, finished with a full-stop.

$severity

This item designates the severity of the log entry. It must be one of the values 0, 1, 2, 3, 4, 5. These values have the following meanings:

• 0 = Debug: should only be used during development
• 1 = Notice: for verbosely logging generic and recurring events (e.g. a user has logged in)
• 2 = Important: events that change something in the system, but are usual (e.g. a post is published)
• 3 = Warning: events that indicate an exceptional or abnormal behaviour (e.g. a file could not be uploaded or something very important was changed)
• 4 = Error: events that indicate a fatal abnormal behaviour (e.g. a database error)
• 5 = Panic: events that indicate a serious damage of the system itself (e.g. cannot connect to the database)

A normal entry should have a level of 1 or 2. If no value for $severity is passed, $severity is set to 1.

$cut

After how many characters the output will be cut off. Defaults to 500.

$userid

This item is the numerical user ID for the user triggering the event. This argument will usually not be required. If no value for $userid is passed, $userid is set to the user ID of the current user.

$time

This item is the Unix timestamp for the time of the event, and if it is used, it must be a Unix timestamp. This argument will usually not be required. If no value for $time is passed, $time is set to the current Unix timestamp.

Examples

Below are usage examples for the logging facility. Remember to use function_exists() to be on the safe side when the plugin is not activated.

wp2syslog('myplugin', "We are running on a {$_SERVER['SERVER_SOFTWARE']} webserver.", 0);
wp2syslog('myplugin', "Damn array! <pre>{print_r($myGoddamnArray, true)}</pre>", 0, 3000);
wp2syslog('myplugin', "Cron backup for foobar successfully finished.");
wp2syslog('myplugin', "A new foo has been added to the bar.", 2);
wp2syslog('myplugin', "Unauthorized user tried to use my features.", 3);
wp2syslog('myplugin', "Creating database table failed.".mysql_error(), 4);

Internationalisation of log messages

Log messages can be fully localized. If you want to do that, it is recommended that you create separate language templates for your plugin and load them independently. It is also recommended to load the textdomain outside of an API-triggered function (i.e. to be directly called), to disable support for multi-language plugins. It would be very confusing to have log messages in different languages.