By Rich Bowen

Last week, O gentle reader, we talked about the Apache access log, and what the information in there means. This week, we're going to talk about the other standard log file: the error log.

As you'll see in coming weeks, these two logs are generated by different processes. And you'll see in this article that the format of the entries in the error log are rather different from the entries in the access log that we saw last week.

But the two logs are similar, in that they both provide a lot of useful information which you can use in analyzing how your server is being used, and what is going wrong.

Where's the File?

Your error log file should be in the same location as your access log file. It will be called error_log, or, on Windows machines, error.log.

The location of your error log can be configured with the ErrorLog directive:

        ErrorLog logs/error.log

The location, unless it has a leading slash, is assumed to be relative to the ServerRoot location.

In a default Apache installation, the log file is located in /usr/local/apache/logs As before, if you installed with one of the various package managers out there, you may find it just about anywhere.

What's in It?

The error log, as the name suggests, contains a record of everything that went wrong while your server was running. It also contains general diagnostic messages, such as a notification of when your server was restarted, or shut down.

You can set your log level higher or lower to control the amount, and type, of messages that appear in your log file. This is configured with the LogLevel directive. The default setting of this directive is error, which tells you about error conditions. For a full listing of the different things you can set it to, see the Apache documentation at http://www.apache.org/docs/mod/core.html#loglevel

In most cases, the things that you see in your log file will be in two categories: document errors and CGI errors. You will also occasionally see configuration errors, and, as I mentioned above, server start and server stop messages.

Document Errors

Document errors are things that are in the 400 series of server response codes. The most common of these is 404 - Document Not Found. 404's are followed by, at least on my server, authentication errors.

A 404 error occurs whenever someone requests a resource--a URL - that is not on your server. Either they have mistyped something, or there was a typo'ed link somewhere, or you moved or deleted a document that used to be on your server.

Incidentally, Jakob Nielson says that you should never move or delete any resource from your website without providing a redirect or some variety. If you're not already familiar with Nielson's writings, you should take a look sometime. http://www.zdnet.com/devhead/alertbox/

When a client is unable to locate a document on your server, you'll see an entry like this in your logs:

        [Fri Aug 18 22:36:26 2000] [error] [client 192.168.1.6] File does not exist: 
        /usr/local/apache/bugletdocs/Img/south-korea.gif

Note that, as in the case of the access_log file, this record is broken down into several fields.

First, we have the date/time stamp. And the first thing that you might notice is that the format is not the same as the format in the access_log. The format that we called the "standard english format." I suspect that this is an accident of history, and that it's probably too late to change it now. I'll have to delve into this a little further and find out.

Next, we have the level of the message. This will be one of the levels specified in the documentation for LogLevel (see link above). error is right between warn and crit. This simply indicates how serious the problem is. A 404 error means that you irritated someone, but your server is not actually on fire.

The next field indicates the address of the client machine that made the request. In this case, it is a machine on my local network.

The last part of the log entry is the actual error message. In the case of a 404, it gives you the full path of the file that the server tried to serve. This is particularly useful when you're getting a 404 on a file that you just know is there. Frequently you have a configuration wrong, or the file is on a different virtual host than you thought, or some other strangeness.

Authentication errors will look very much the same:

        [Tue Apr 11 22:13:21 2000] [error] [client 192.168.1.3] user rbowen@rcbowen.
        com: authentication failure for "/cgi-bin/hirecareers/company.cgi": password
        mismatch

Note that document errors, since they are a direct result of a client request, will be accompanied by an entry in access_log as well.

CGI Errors

Perhaps the most useful use of the error is troubleshooting misbehaved CGI programs. Anything that a CGI program emits to STDERR (Standard Error) gets spewed directly to the error log for your perusal. This means that (well-written) CGI programs, when they go south, will tell you, via the log file, exactly what the problem is.

The downside to this is that you end up with stuff in the error log that is not in any well-defined format, and so it makes it very hard to have any automatic error-log parsing to get useful information out.

What follows is an example of an entry in my error log from when I was hacking on some Perl CGI code:

        [Wed Jun 14 16:16:37 2000] [error] [client 192.168.1.3] Premature 
        end of script headers: /usr/local/apache/cgi-bin/HyperCalPro/announcement.cgi
        Global symbol "$rv" requires explicit package name at 
        /usr/local/apache/cgi-bin/HyperCalPro/announcement.cgi line 81.
        Global symbol "%details" requires explicit package name at 
        /usr/local/apache/cgi-bin/HyperCalPro/announcement.cgi line 84.
        Global symbol "$Config" requires explicit package name at 
        /usr/local/apache/cgi-bin/HyperCalPro/announcement.cgi line 133.
        Execution of /usr/local/apache/cgi-bin/HyperCalPro/announcement.cgi 
        aborted due to compilation errors.

OK, this entry actually does follow the same format as the 404 error above, in that it has a date, error level, and a client address. But the error message itself is several lines long, which tends to confuse some log-parsing software.

Now, even if you don't know Perl, you should be able to look at the error messages above, and glean some useful information about what went wrong. At the very least, you can tell on what lines I screwed up. Perl is really good about telling you where you made a mistake. Your mileage may vary, based on what language you are using.

Without logs, it would be very difficult to troubleshoot most CGI programs, because running the program from the command line is a rather different environment than running it from a web server.

Nine times out of eight, when someone complains on a mailing list, or on a newsgroup, that they are having CGI problems, and are getting a page that says something like "Internal Server Error", they have not looked at the logs, or are unaware of their existence. Very frequently, a glance at the logs will tell you exactly what the problem is, and tell you how to fix it.

How Do I Watch the Log?

Often, I'll tell people that I watch the server logs while I am developing, so that I know immediately what is going wrong. This is frequently met with a blank stare. At first I assumed that this meant "well, of course you do." Later I discovered that it usually means "I have no idea how one would do that, but I'm not about to admit it."

OK, so here's how you do it. Telnet into the machine on which your Apache server is running, and type the following command:

        tail -f /usr/local/apache/logs/error_log

This will show the last few lines of your log file, and, as lines are added to the file, it will show you those as they happen. Neat, huh?

What, you're running on NT. No problem. There are a few ways around this. There are a variety of Unix tools packages available for Windows. My personal favorite is one called AINTX, which you can find at http://maxx.mc.net/~jlh/nttools/index.htm

Another alternative is to use the following Perl code, which uses a module called File::Tail

        use File::Tail;
        $file=File::Tail->new("/some/log/file");
        while (defined($line=$file->read)) {
                print "$line";
        }

Whatever your method, it's extremely good practice to keep several terminal windows open, with your error log tailing in one window, and your access log tailing in the other, while you work on your site. This will tell you what is going on as it happens, and so you know about problems before the customer has a chance to call you about them. That way, you can either answer the phone with "yes, I know, and it's already fixed," or, perhaps, not answer the phone at all. ;-) Shh. Don't tell my customers I said that.

What's Next?

Next week, I'll be talking about custom server logs--how you can build logs that contain only the information that you are interested in, and nothing else.

After that, we'll discuss log processing--how to glean useful information out of these log files.

Finally, we'll talk about redirecting your log files to a process, rather than to a file, so that you can process that data as it is being generated. This will cover such things as sending your logs to a database, and perhaps sending email to the sysadmin when something particularly nasty happens, and other things like that.

And whatever else people write me about between now and then, I'll try to tackle as well. Send me a note at and I'll see what I can do.

Want to discuss log files with other Apache Today readers? Then check out the PHP discussion at Apache Today Discussions.