Web Analysis Using Analog
One of the many responsibilities of being a webmaster is keeping tabs on the traffic your site receives. This information can help when it comes time to update: you will know which pages are requested most often and which could use a little more promotion.
Analog is an open-source program that analyses log files from web servers, creating as many as 32 different reports. It works on many operating systems, including Linux, and supports 35 different languages. It's extremely flexible and fast. Its author is Stephen Turner, a Research fellow at Sidney Sussex College at the University of Cambridge. His research has to do with mathematical problems in communications networks, so he has a good solid background when it comes to log file analysis.
Analog's versatility can make it seem very complicated; it has over 200 configuration options. The number of choices is also what makes it very useful for hostmasters and webmasters alike.
A common question on the analog-help mail list is, “How do I setup Analog for virtual hosts?”. This article will cover setup for both virtual hosts and individual pages. In addition, I'll describe how to use configuration and script files to get monthly, hourly, daily and specialized reports.
I've used Analog for several years, first on a FreeBSD system; I was a dial-in customer curious about my personal web pages. Later, I used Analog with Win95/98, and now use it on a Linux system as a web administrator. An example of my publicly available log analysis setup can be found at http://vcsweb.com/logs/.
Analog is the type of program that no two users will use in the same way, due to the vast number of options, only the items I have experience with will be discussed.
Before delving into Analog's configuration files, it's important to understand what you can and can't learn about your site from log files. First, the log files should be considered only as an estimation of traffic. Log references aren't available when web pages have been accessed from either browser or ISP cache files. According to Analog's author, it's impossible to tell the number of distinct visitors or the total number of visits.
The bottom line is that HTTP is a stateless protocol. People don't log in and retrieve several documents: they make a separate connection for each file they want. Many times, they don't even behave as if they were logged in to one site. Hence, Analog's emphasis on requests, rather than visits.
What we can learn varies, depending on what the web server writes to the logs. In general, this usually includes the computer name (or IP number) requesting information, whether the request was for a page (generally an HTML document) or another type of file, the status of the request, the time and date the request was made, and the number of bytes transferred. If the log file reports it, we can also learn which web site or page referred the visitor to our site and the browser they were using.
Analog's home page is at http://www.analog.cx/, and it can be downloaded from www.analog.cx/analog4.01.tar.gz. This web site also lists several mirror sites for the file.
Installation is rather painless: simply type make while in the analog4.01 directory. Several options can be set in the analhead.h file prior to using the make command, such as host or organization name, the log file path and name; I've found it more practical to use the configuration files for these items instead. The only item I needed to change in analhead.h was the directory path of /usr/local/etc/httpd to /etc/httpd so it matched my Red Hat Linux system, which allows me to use it from the /etc/httpd/analog directory.
It should be noted that Analog will work from any directory, as long as it can find its /lang directory. This can be accomplished by adding the language file and path name to Analog's configuration file(s), but for my use, it's easier to compile the program to the directory in which I want to work. When using the program as a single user, you can compile and use it from your home directory.
As a second step to installing Analog, I highly recommend viewing and bookmarking the local set of Analog's documentation in your favorite web browser. If you use Analog for creating HTML-format reports, this lets you have the documentation open in one browser window while viewing the reports you've generated in another. Analog isn't the type of program for which you can read the documentation from start to finish, create one configuration file and quit. Rather, the documentation provides information on each of its over 200 commands; you experiment to find the settings that suit your preferences.
Analog can be configured to use customized log formats, which is a very good thing if you happen to have log files in various formats created by different servers. Even though I've used a number of different servers, I've been able to continue using Analog to analyze new and old log files (of different formats) by listing the type of log format before giving the name and path of the log file. I now use the Apache web server's combined log format, which produces a common log file that lists the referrer and browser information with the log entry for each access. Otherwise, I'd have separate log files, one for the referrer and another for the browser, and would need to include these log files when working with Analog's configuration files.
If you're a hostmaster, you can configure Apache to use a different log file for each virtual host. This keeps the information for each host separate and makes using Analog to analyze your virtual host log files much more straightforward. This is done using Apache's virtual host directive:
<VirtualHost vhost1.com> ServerAdmin webmaster@vhost1.com DocumentRoot /www/docs/vhhost1.com ServerName vhost1.com ErrorLog logs/vhost1.com-error_log CustomLog logs/vhost1.com-access_log combined </VirtualHost>
While you can use Analog with just the analog.cfg file to tell it what to do and where to save its report, if you want to create different reports for virtual hosts and individual pages, it's best to use multiple configuration files. Each configuration file serves a different purpose and can be combined with script files containing command-line switches for Analog.
In this scenario, Analog is run not once, but several times; each run creates a separate report. The analog.cfg file includes only a very few base commands that relate to our main site, not the virtual host sites. When creating reports for virtual hosts, I exclude analog.cfg from being called with the -G command-line switch.
The basic arrangement is similar to a pyramid format. All major items are in a master.cfg file to cover the broad category of all virtual hosts on our system. Items relating only to a specific virtual host and their general preferences are in the next tier, and finally, individual page.cfg files are in the last category. This allows me to create specialized setups as needed and still track individual hosts, sites and pages without making major changes.
When Analog is run for a virtual host, the master.cfg file is called first, followed by the master-vhost.cfg (I replace “vhost” with the name of the host when naming the file), and finally, single-page configuration files for separate pages. An example master.cfg file is included here (see Listing 1).
An example vhost.cfg file is shown in Listing 2, and as you can see, it's fairly general, since most of the report formatting and such is handled by the master.cfg file. The vhost.cfg file can be used to create a “total activity” report for the virtual host. The command-line prompt (or script file), shown without paths for clarity, is:
analog -G +gmaster.cfg +gvhost1.cfg +Ovhost1-total.html
The -G tells Analog not to use analog.cfg (which is used for the main host only). +g is used whenever we use additional configuration files: there's no space between it and the file name. +O designates the output file name: it's the letter O, not the number zero.
Single configuration files are used to give the basic information on the files(s) to include in the report (using the FILEINCLUDE command). The HOSTNAME and HOSTURL directives are the items that will appear at the top of each report after the words “Web Server Statistics for”. For individual pages, we use the name and URL of the page rather than the host name or URL. A single-page configuration file can be three or more lines, as shown in Listing 3.
Notice that the log file to use, output file and report-formatting commands aren't included; these items are set either in the master.cfg files or within the script file when Analog is run. This lets me use the same information when creating the daily and monthly reports, even though the two reports are very different.
The FILEINCLUDE command causes Analog to search through the logs and retrieve data relating to only the file you've specified. It's a very powerful command, and is normally used in the configuration files for individual pages or sites. It can also be used with a wild card; if I wanted to include all files in the widgets directory, I would use:
FILEINCLUDE http://vhost1.com/widgets/*
The command line used to create a daily report for this page (all on one line), shown without path information for clarity, is:
analog -G +gmaster.cfg +gmaster-vhost1.cfg +gwidgets.cfg +Owidget.html
I mail a monthly report of web stats to a few of my customers who aren't on-line and who have found the daily reports were too long to print and took too much time to edit. To solve the problem and save time, I created month-vhost.cfg files which create ASCII text format reports. The month-vhost.cfg files are used in conjunction with the individual configuration files described above. A sample month-vhost.cfg file is shown in Listing 4. To produce the monthly text reports, +a is used on the command line to designate ASCII output:
analog -G +gmonth-vhost1.cfg +gwidgets.cfg\ +Owidget.txt +a
As I'm responsible for the entire system, it's important to have a review of the overall picture, including all our hosts. To accomplish this, I have a separate activity configuration file and run Analog once a day with a cron entry. The activity configuration file includes the log files for all hosts, and this requires giving extra information to Analog so it can format the results; otherwise, /index.html would be considered as belonging to one host. Commands in configuration files must be on one line. The LOGFILE command allows you to specify the name of the host corresponding to the log file (ignore line wrap):
LOGFILE /var/log/httpd/access_log http://main-isp.com/LOGFILE /var/log/httpd/vhost1.com-access_log http://vhost1.com
Our daily reports are published on the Web, so I prefer to keep cgi-bin information confidential. A daily webmaster e-mail report (described below) takes care of informing me of web-related exploits, so the information isn't required on the public reports. The cgi-bin directories and file names need to be aliased so that this information isn't available to the public. Analog can use output aliases to give control over how a file or directory is displayed within reports. This can be used to keep complete path and file names from the public, if desired. I use the following alias commands in my master.cfg files to translate cgi-bin path and file information to simply admin (ignore line wrap):
REQOUTPUTALIAS */cgi-bin/* "admin" DIROUTPUTALIAS */cgi-bin/* "admin" FAILOUTPUTALIAS */cgi-bin/* "admin" FAILREFOUTPUTALIAS */cgi-bin/* "admin" TYPEOUTPUTALIAS */cgi-bin/* "admin" REFOUTPUTALIAS http://main-isp.com/cgi-bin/* "admin" REDIROUTPUTALIAS */cgi-bin/* "admin"
The last two items are used in Virtual Host master.cfg files, so we're still not giving away information on other local hosts in referral reports. If you want to be more specific, you could alias file names to match what they do, such as the following line (ignore wrap):
REQOUTPUTALIAS */cgi-bin/bannerpro.pl* "Banner Program"
I have a number of partial pages such as footers, sidebars and headers in a global directory that could cause Analog to inflate the request totals out of proportion. When you exclude information, it usually relates to the entire host, so it makes sense to use exclude commands in the master.cfg instead of in individual page or site configuration files. To exclude global directory accesses from being counted as requests, I use the command:
REQEXCLUDE */global/*
Partial web pages, such as header-and footer-type files, can also be excluded individually with the PAGEEXCLUDE command:
PAGEEXCLUDE */footer.htmlor (for those who use PHP):
PAGEEXCLUDE */footer.php3
I use a small script to receive a daily Webmaster report. This is basically the same as the Activity report, but it includes information that's excluded from the public version. When I read my e-mail in the morning, I can see the status of my system over the last 24 hours. The script runs from cron, and since Analog will send results to STDOUT if no outfile is listed, I use this to my advantage. The output becomes the body of the e-mail. A bare-basics webmaster.cfg file is included in Listing 5.
Using script files allows Analog to create several reports, one after the other. After the configuration files, the script files are the next step. I use one hourly script to create the Activity Report, and two daily script files: one for daily reports that are published on the Web, and the other to send the webmaster e-mail each morning. A monthly script file creates the text files that are mailed to customers each month. These scripts are shown in Listings 6-9.
When working with the web-published statistics reports, or when simply checking them periodically, it's much easier if you create an index web page for reports and bookmark it. While this may seem a common-sense thing to do, I remember my early days of experimenting with Analog and fumbling around directories to find the resulting reports. Every step toward making analyzing our logs easier means we have a little extra time to work on developing other web projects to add to the list and continue the cycle.
