How to set up an e-mail log using the Stanford Web Application Toolkit

From Web Services Wiki

Jump to: navigation, search

Contents

Problem

You want to set up an e-mail log so that you receive the latest logs in your inbox with a specified delay between messages to prevent flooding.

Solution

Use one of the StanfordLog classes for logging to a file or a database and configure its e-mail settings.

Basic usage

First, configure either a StanfordLogFile or StanfordLogDatabase. The file or database table will function as a buffer between e-mails. It will also allow us to keep track of when the last e-mail was sent. Once the logging class is set up, create a new StanfordLogEmailSettings instance. Configure the e-mail settings and then attach them to the logging class using the load_email_settings function.

The example below uses a StanfordLogFile, but a StanfordLogDatabase works the same way with no additional configuration.

// Include StanfordLog
require_once("stanford.log.php");
 
// Create a new StanfordLogFile (or StanfordLogDatabase)
$log = new StanfordLogFile("/path/to/my.log");
 
// Create a new StanfordLogEmailSettings
$settings = new StanfordLogEmailSettings();
 
// Configure e-mail settings
$settings->set_recipient("nobody@stanford.edu", "My Name");
$settings->set_subject("StanfordLog Update");
$settings->set_delay(60*60);  // One hour between e-mails
 
// Load e-mail settings into $log
$log->load_email_settings($settings);
 
// E-mail functionality is now enabled
// Calling $log->append will add new messages to the buffer and auto-detect when it is time to send the next e-mail
 
// Log a message
$log->append("This is a test.");

Additional configuration options

StanfordLogEmailSettings can be further customized. All of the options are listed below.

// set_delay
//  Sets the minimum delay between e-mails in seconds
 
$settings->set_delay(60*60*24); // One day
 
// set_probability
//  Sets the probability that the log will be read upon loading of the e-mail settings
//  to determine whether it is time to send the next e-mail.  Set this to a higher value
//  (near 1) to receive logs in a more timely manner, but beware of a performance hit.  The 
//  default value is .1.  The log file is read each time $log->append is called no matter
//  what the probability's value is.  A valid probability is >= 0 and <= 1.
 
$settings->set_probability(.5); // The log is scanned 50% of the time when you call load_email_settings
 
// set_recipient
//  Sets the recipient of the e-mail
 
$settings->set_recipient("nobody@stanford.edu", "My Name");
 
// add_recipient
//  Adds a recipient to the message (e-mails sent using StanfordLog may have any number of recipients)
 
$settings->add_recipient("another_person@mydomain.edu", "Another Person");
 
// set_sender
//  Sets the sender of the message
 
$settings->set_sender("log@mydomain.edu", "StanfordLog");
 
// set_subject
//  Sets the subject of the e-mail
 
$settings->set_subject("My site's e-mail log");
 
// set_truncate_on_send
//  If true, the log is truncated (emptied) after each e-mail is sent.  Performance will increase with this setting turned on due to a smaller log size.
//  If false, the log is preserved.  Default setting is false.
 
$settings->set_truncate_on_send(false);

Sample e-mail log

Below is a sample message sent using StanfordLog.

Subject: StanfordLog Update
 
Body:
"2008-11-06 16:57:57",256.1.2.3,/~sunetid/cgi-bin/log.php,"","This is an error message."
"2008-11-06 16:59:33",4.5.6.256,/~sunetid/cgi-bin/log.php,"","This is a different error message."
"2008-11-06 17:10:15",7.256.8.9,/~sunetid/cgi-bin/log.php,,"display=1&id=4","You should probably fix this."

Discussion

Why should I use this tool?

PHP provides a convenient means of sending e-mail through code, which makes it easy to set up a script to e-mail the administrator when a major function stops working. Unfortunately, it offers no flood control. Often when a major error occurs, such as when the database server is inaccessible, it happens many times in a short period. If a script were set up to send a message every time one of these errors were raised, the admin would be flooded with messages. The functionality provided in this recipe resolves this problem by buffering messages and adding a delay between the actual sending of each e-mail. We suggest you set the delay to 10 minutes (600 seconds) or something else more manageable to suit your needs, depending on how often the function is called and the severity of the errors it handles in your application. The default is 10 minutes.

How does the class work?

Each time an entry is written to the log, the file or database table is scanned to find out when the last e-mail was sent. If sufficient time has passed since the last e-mail (which is determined by comparing the time of the last sent message and the specified delay to the current time), a new e-mail is sent and a special marker is written to the log file indicating the current time and that a message was delivered. A sample marker is shown below:

"2008-12-15 15:16:36",20.95.256.3,/~my_sunetid/cgi-bin/log.php,"","StanfordLog e-mail sent"

Since the marker has the same formatting as the rest of the log, it may easily be parsed and filtered out, if desired.

Is there an easier way to log via e-mail if I don't need flood control?

Yes, PHP provides a simple function called error_log that can be configured to send e-mail. To learn more about error handling in PHP, visit the PHP Cookbook.

Personal tools