December 21, 2014
Hot Topics:

Monitor PHP Application Errors and Messages with syslog

  • March 17, 2004
  • By W. Jason Gilmore
  • Send Email »
  • More Articles »

If nothing else, programmers are eternal optimists. We enter each project somehow convinced of a perfect outcome, despite the often considerable technical and logistical difficulties inherent to our profession. Computer Science is after all still in its infancy, and our tools, not to mention development techniques, remain quite immature. Resultingly, one outcome that you can be sure of as you embark on the next pursuit of programming perfection is that unexpected errors will arise, many that will certainly require immediate attention. Therefore if perfection isn't an option, striving towards it by implementing effective error detection and reporting capabilities in your software is the next best thing.

In this article, I'll show you how you can log your PHP application errors using the standard Unix logging mechanism, syslog. For starters, I'll offer a brief introduction to syslog, and demonstrate how you can configure the syslog daemon to route PHP messages to their own log file. Next, I'll introduce PHP's syslog functions, and demonstrate how to send application messages to your operating system's syslog facility. First, however, I'd like to take a brief moment to further introduce syslog for those of you presently unfamiliar with this standard Unix logging mechanism.

Syslog Basics

The average server consists of numerous mission-critical services (Apache, PHP and MySQL, for instance). All such services, not to mention the applications that sit on top of them, must be continuously monitored to ensure proper operation. However, actually using the applications and services to ensure availability simply isn't practical; instead, standard practice dictates that diagnostics and status messages are written to a log file, which can then be parsed and reviewed at our leisure. Yet consistency breeds efficiency, and therefore it would be ideal to log all messages from all applications and services using a standard location and format. Syslog affords us that opportunity. An open specification, syslog support can be written into any language or application, as has already been done with PHP.

On a typical server, syslog-managed log files are stored in /var/log/. Keep in mind that you're not required to follow this practice; in fact, syslog even allows you to write locally-generated messages on a remote server! If you're not familiar with the standard log files, take a moment to navigate on over to this directory and nose around. Regardless of which application, all messages follow a standard format, consisting of a timestamp, host name, system component, and log message. For example, consider this snippet pulled from my Linux server:

Mar 15 13:37:20 www.example.com sendmail: sendmail startup succeeded
Mar 15 13:37:22 www.example.com crond: crond startup succeeded

In this sample, two messages coming from the server www.example.com were logged two different system applications, namely sendmail and crond.

Syslog effectively manages log entries by assigning each two characteristics: the severity level and the log type (technically referred to as the facility). The facility determines the the service area from which the entry originates. In total there are eight supported severity levels, listed here in order of increasing severity: debug, info, notice, warning, err, crit, alert, and emerg. Although I won't get into the details regarding the meaning of each, you should be able to generally interpret their meaning simply based on their respective titles. Likewise, there are twelve supported facilities: auth, auth-priv, cron, daemon, kern, lpr, mail, news, syslog, user, uucp, and localn where n ranges from 0 to 7. Each of these has special significance on Unix-based platforms; if you're not already familiar with these facilities I'll leave it to you to perform the necessary research.

Because the last of the aforementioned facilities, localn, is intended for user-defined services, you can choose one to monitor PHP-specific events, and log those event messages to a separate file. For purposes of this example, I'll use local0. Keep in mind that its possible that other user-defined facilities might already be using one or more of the localn facilities. You can determine which user-defined facilities are presently being used by consulting your syslog daemon configuration file, syslog.conf file, typically located in /etc/. Although it's out of the scope of this article to formally introduce this file, for purposes of illustration I'll present a sample file, which should provide some insight into how I direct the PHP-specific messages to a file named php.log residing in /var/log/:

# Various irrelevant items cut to save space...

# Note how I append ";local0.none" to the end of this to prevent
# PHP-specific messages from going to /var/log/messages

*.info;mail.none;authpriv.none;cron.none;local0.none /var/log/messages

# Various irrelevant items cut to save space...

# Save PHP messages to php.log
local0.* /var/log/php.log

Once you've made the necessary adjustments to your configuration file, you can restart the syslog daemon like so:

%>/etc/init.d/syslog restart

PHP's Syslog Functions

PHP's syslog functions are surprisingly simple to use. In fact, there are only four of them, each of which is introduced in this section. For a formal explanation of the input parameters and return values of each, please consult the PHP manual. However after reviewing a few examples, offered in the next section, I'd venture that you'll have a pretty good grip on their use.

  • define_syslog_variables(): This function initializes a number of constants which are subsequently used in the other syslog functions. You have the option of executing this automatically by enabling the php.ini configuration parameter define_syslog_variables, however for performance reasons I suggest disabling it and executing the function only when you're about to interact with syslog. This function takes no input parameters, and returns no value.
  • openlog(): This function opens a connection to syslog. Three input parameters are required, namely the message identity (you can think of this as the message title), logging options, and the logging facility, which for purposes of our example will be LOG_LOCAL0. It returns TRUE on success and FALSE otherwise.
  • syslog(): This function is reponsible for writing the message which will be sent to syslog via the connection opened by openlog(). It takes two input parameters, namely the message severity level (enumerated earlier in this article) and the actual message. It returns TRUE on success and FALSE otherwise.
  • closelog(): This function closes the connection to syslog. It takes no input parameters. It returns TRUE on success and FALSE otherwise. Although use of this function is optional, I recommend including so that the action is clearly denoted in your script.

An Example

Now that you're apprised of the foundational concepts to implement this feature in your PHP applications, let's consider an example. Suppose that you want to log any failed MySQL server connection with severity level alert:

<?php
   $dbh = mysql_connect("localhost","jason","secret");
   if (! $dbh) {
      define_syslog_variables();
      openlog("mysql", LOG_NDELAY, LOG_LOCAL0);
      syslog(LOG_ALERT, "Could not connect to MySQL server!");
      echo "<p>Sorry, the MySQL database server is unavailable at this time.</p>";
   }
?>

Executing this script will result in the following message being logged to the php.log file (assuming the connection attempt failed!):

Mar 15 21:45:29 www.example.com mysql: Could not connect to MySQL server!

Conclusion

Logging application information via syslog is a highly convenient way to consolidate your log data to a standard location and format. Doing so will go a long way towards eliminating unnecessary development and maintenance overhead as a result of needing to devise and deploy custom logging methodologies.

Have a question or comment? E-mail me at jason@wjgilmore.com. I also welcome ideas for future articles!

About the Author

W. Jason Gilmore is an Editorial Director for the technical book publisher, Apress. He's the author of the upcoming book, PHP 5 and MySQL: Novice to Pro, due out by Apress in 2004. His work has been featured within many of the computing industry's leading publications, including Linux Magazine, O'Reillynet, Devshed, Zend.com, and Webreview. Jason is also the author of A Programmer's Introduction to PHP 4.0 (Apress, 2001. 453pp.). Along with colleague Jon Shoberg, he's co-author of "Out in the Open," a monthly column published in Linux Magazine.






Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Sitemap | Contact Us

Rocket Fuel