Refine and debug PHP applications with syslog

PHP version of venerable UNIX syslog offers a simple, effective debugging tool

An old technique for exploring a running program is to place code that "displays" the current value of variables at strategic points. But how is this done without interfering with the standard output of the program? With PHP's syslog() facility, examining these values is easy. Find out how.

William B. Zimmerly (bill@zimmerly.com), Freelance Writer and Knowledge Engineer, Author

Photo of Bill ZimmerlyBill Zimmerly is a knowledge engineer, a low-level systems programmer with expertise in various versions of UNIX and Microsoft® Windows®, and a free thinker who worships at the altar of Logic. Bill is also known as an unreasonable person. Unreasonable as in, "Reasonable people adapt themselves to the world. Unreasonable people attempt to adapt the world to themselves. All progress, therefore, depends on unreasonable people" (George Bernard Shaw). Creating new technologies and writing about them are his passions. He resides in rural Hillsboro, Missouri, where the air is fresh, the views are inspiring, and good wineries are all around. There's nothing quite like writing an article on UNIX shell scripting while sipping on a crystal-clear glass of Stone Hill Blush. You can contact him at bill@zimmerly.com.



16 October 2007

Also available in Russian Japanese

Programming a computer is a tedious business, but it's fun, too. One of the fun aspects of programming is learning about new ways to use an old tool. Recently, I was contracted to fix a dozen bugs in a large, complex, Linux®, Apache, MySQL, and Linux, Apache, MySQL, PHP/Perl (LAMP)-based content-management system (CMS). The architecture of the CMS was the standard LAMP model, with Enterprise Red Hat Linux running Apache V2.0. The code that drove the Web sites consisted of a few hundred PHP source modules spread out over 30 subdirectories in the Apache document root directory. The Apache and MySQL portions of the system required no changes, so all my bug-busting activities were to occur in the PHP workspace.

After spending considerable time learning how the CMS worked, I grew to appreciate the system's elegant design and I realized that, as in most mature programming environments, this system relied on only a small number of the available PHP functions. (Shades of the old 80/20 rule here, where 80 percent of the work is accomplished with 20 percent of the available functions.) This article shows how the process of debugging an unknown but complex system can help you learn about those little-used functions and provides examples of how to apply your new knowledge by using the rich functionality of the syslog() function.

Under the microscope

With literally hundreds of functions available in the PHP programming language, some (dare I say most?) functions are never used unless you read about them in articles like this one. Another way to learn more about the language is to debug programs that others have written in it. I'm always impressed by the creative ways in which programmers use the tools.

Debugging, like computer programming, is part science and part art. When tracking down obscure bugs in a system that you didn't create, you need to have a good feel for where they manifest themselves in the code. With hundreds of code modules to deal with, a good place to begin is where the output revealing the bug is found, then work your way backward from there to isolate the problem.

Say, for example, that a calculated value that was being output is known to be incorrect. You must devise some way to see the intermediary values that lead up to the problem. Another problem may manifest itself with bad data coming from an important database query. You need to be able to see the SQL statement generated (and submitted by the code to the MySQL engine) to see whether that's where the problem lies.

One age-old technique for doing this is to insert code that simply prints these strings and values. Unfortunately, with a tool like PHP, or any Web-based application, you don't want to clutter up the natural output of systems like this (that is, HTML code being sent to the browser) with debugging information, especially if the system you're examining is a production server.

You could create a custom logging file and write log messages to it, but why not use the tools that have already been provided for you? Always remember: Don't bury your tools. The time spent seeing whether the language authors have already provided a library routine or function to do something you suspect would be a commonly needed function is well spent. In fact, anytime you suspect that something should obviously be part of a programming package, it probably is.

I realized that what I needed to use was something similar to the syslog functionality of UNIX®. I thought it likely that PHP would have a hook into the syslog functionality, so upon a quick review of the PHP documentation, I found it! The PHP syslog() function is one that I had overlooked for many years until I was contracted to do this project. With syslog(), I was able to hunt down and exterminate most of the bugs in the production system without introducing side effects other than the minute amount of time it took for each function to execute.

As you grow in your knowledge and become more skilled in your craft, different ways of doing things become apparent, and some way will eventually become the obvious way to perform the required task. What you must always keep in mind is that what is obvious to you is not obvious to other people. What may be simple to you can present a mountain of complexity to others.

Using a tool like the syslog() function keeps complexity under control and provides the added benefit of allowing easy customizations through configuration files, such as syslog.conf. For example, you can insert code to format a SQL statement, log it to syslog(), and pass it to MySQL for execution. Later, a slight modification of the syslog.conf file sends the text to a different log file or perhaps just to the bit bucket. Weeks or months later, if it becomes necessary to see what's happening again, another simple change to the syslog.conf file will restore the functionality.


syslog

syslog has a rich and colorful history in the UNIX world. Originally developed as part of the Sendmail project, syslog had proven to be so useful that many other tools have incorporated in its functionality, proving that the simplest ideas are sometimes the most powerful.

In a nutshell, syslog allows applications to write tagged messages to a common set of system log files that can reside where it's convenient for the programmers and network administrators to access. This means, for example, you can configure syslog on a Web server to log system messages on a different server — one that is perhaps a few layers deeper behind the security firewalls and easier for the aforementioned administrators to access. But for my purposes, I just accept the default behavior of files being written to the /var/log directory.

The syslog mechanism is started at boot-up, and its initial behavior is defined by the rules in the syslog.conf file. These rules enable you to finely tune what can and cannot be logged with the mechanism — which, on a high-volume, hard-working server can translate to log files of a manageable size.

Each rule consists of two fields: selector and action. Basically, the selector field selects what facility will be logged (for example, kern, user, mail, lpr) and what priority the facility has. The priority field contains a keyword, such as debug, info, notice, or warning. And the action field of a rule defines what to do with messages of a kind that match the selector field. The rules can specify which file to log the message to, what machine to send the logging message to, what user to send the message to (in the form of console messages), etc.


Logging

Study the info and man pages associated with the syslog facility to learn how to configure the system for your needs. In my case, I needed to know what the value of various PHP variables were at different times while the production CMS system was running. I also needed to know when certain modules were started and ended, as well as what various intermediate variable values were. Before getting into specifics about what to log, let's set up the basics for logging.

With your favorite editor, create the file shown in Listing 1, name it test.php and put it where your Apache document root is found (on my system, it's /var/www).

Listing 1. test.php
<html>
  <head>
    <title>PHP Test Page</title>
  </head>
  <body>
    <?php
    syslog(LOG_NOTICE, "{$_SERVER['REMOTE_ADDR']}: test.php - PHP Index page accessed.");
    echo '<p>PHP Test Page</p>';
    ?>
  </body>
</html>

You should have PHP installed and configured, as well. If not, check Resources for links on how to do this. If you configured everything properly, you should see the following text in your browser when you access the page with the URL http://localhost/test.php:

PHP Test Page

Next, open an X terminal window and type the following command to see what was logged to the /var/log/messages file:

tail /var/log/messages

If all goes well, you should see a line like this one near the end of the listing:

Jul 23 14:43:42 localhost apache2: 127.0.0.1: test.php - PHP Index page accessed.

If you did, that's great. You have now verified that all you need to do to begin detailed debugging of the complex system you're working on.

I have found it a good practice to use syslog() for all the PHP/MySQL calls so that every time you interact with the Web site, you can see which SQL queries are generated in real time to build the page returned to you. A handy way to make this work is to open a spare X terminal window and use the tail command with the -f option for "live" viewing of the messages log:

tail -f /var/log/messages

What to log

Now that you've verified that the logging works and that you can see the results of the logging mechanism, here are a few tips for shortening the process of learning a foreign system as quickly as possible using these tools.

It's important to know what modules do what beyond what their documentation may say. For this reason, I like to include logging messages that mark the beginning and end of the modules. In this way, you can play with the pages of the Web site, keeping an eye on the spare X terminal window running the tail -f /var/log/messages command. In this way, you see which modules execute and in what order every time the browser requests a new page.

I also like to log the boundaries between different programs being called into action during the running of the PHP code. Examples include when the MySQL calls are made to query the databases or when external programs are called to make formatting changes to data (Extensible Stylesheet Language Transformation (XSLT) engines, for example). The very practice of systematically inserting these checkpoints into each PHP code module helps you get used to the names and locations of the modules. When the code sends you messages you see in the spare X terminal while browsing various pages, you get important feedback that facilitates and enhances your knowledge of the system.


Conclusion

The syslog facility is a powerful tool for debugging an application someone else wrote. It allows you to watch which modules are being executed, which SQL statements are executing, and which variable values change as you navigate the Web site. This helps pinpoint the modules in which you're likely to find problems.

Resources

Learn

  • Learn more about the syslog() function.
  • Discover the history of syslog on Wikipedia.
  • PHP.net is the central resource for PHP developers.
  • Check out the "Recommended PHP reading list."
  • Browse all the PHP content on developerWorks.
  • Expand your PHP skills by checking out IBM developerWorks' PHP project resources.
  • To listen to interesting interviews and discussions for software developers, check out developerWorks podcasts.
  • Using a database with PHP? Check out the Zend Core for IBM, a seamless, out-of-the-box, easy-to-install PHP development and production environment that supports IBM DB2 V9.
  • Stay current with developerWorks' Technical events and webcasts.
  • Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
  • Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  • Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.

Get products and technologies

  • Innovate your next open source development project with IBM trial software, available for download or on DVD.
  • Download IBM product evaluation versions, and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=260778
ArticleTitle=Refine and debug PHP applications with syslog
publish-date=10162007