Installing Analog on Mac OS X Server
Updated 24 September 2002
 |
AnalogWe tested a fresh installation of Analog 5.24 with Mac OS X 10.2 (with the latest Developer Tools and BSD SDK) on 23 September 2002 and found no problems installing or running the software. In fact, to our enjoyment, it is no longer necessary to modify the Makefile (as described below) in order to get Analog to compile under Mac OS X Server. Analog also reads an interprets the default logfile format used by Apple (a sort of semi-combined format) without modification, though we still recommend changing your settings. |
What is Analog?
Analog is a log analysis program. It will take all of the information your Web server produces about visits and visitors to your Web site.
Why should you use it?
A few reasons: On the not so technical side, it is free (though a donation to the author is always appreciated), stable, supported and very powerful and if you run a Web site, you really need it.
Why? You spend quite a lot of time developing your Web sites. Being as creative as possible. By using Analog you can determine if your work is effective. You can see if visitors to your side are being guided to the pages you want them to go to. Sometimes it is a shock to realize that people are never getting to that great page you designed. Using Analog makes it easier to determine why. Is anyone making it past the home page? Maybe your navigation is not clear enough. Are you using things like Flash and Java? A look at the browser report might show you that a large number of visitors don’t have a browser that can support those. You might also be coding for the “least common denominator” browser only to find that 95% of your traffic is using the most current version of Internet Explorer. You should always consider all potential users but at least you can use Analog as a way to be a bit more educated about how to target design.
Lastly, if you are working with a client, you can show them reports that people are getting to the site and your design is working.
Step 1: Building Analog
Installing Analog on Mac OS X Server is a rather simple process. One thing to be aware of is it will not compile unless you have the December 2001 Developer Tools update. You also will need admin access to the machine so you can run sudo.
So, now that you have that installed, let’s get started.
First, go to http://www.analog.cx/ and get the source distribution for Analog. As of this writing, the latest version is 5.2.1. Avoid getting the precompiled version. It runs as a GUI-based app and does not give you the level of command line control you really want. The latest source is available here: http://www.analog.cx/analog-5.21.tar.gz.
Once you have the source downloaded you need to extract it. If you have StuffIt, it might have already done the extraction for you. If not, go to the directory where you downloaded it and follow these steps:
gzip -d analog-5.21.tar.gz tar –xvf analog-5.21.tar
Once this is done, change directories to analog-5.21/src. Using the editor of your choice edit the Makefile (e.g., vi Makefile) You need to change two things in this file. Don’t change anything else unless you really know what you are doing. On the fifth line, you will see ?CC = gcc”; this needs to be changed to read “CC = cc” Mac OS X ships with a compiler called cc, it doesn’t ship with gcc. On line 26, set the OS = flag to “OSX". When done it should look like Figure 1.
# Makefile for analog 5.21 # Please read docs/Readme.html, or http://www.analog.cx/ # This is a general Unix-like Makefile: Makefiles for other OS's can be found # in the "build" directory. CC = cc # which compiler to use: eg cc, acc, gcc. NB Different # compilers need different CFLAGS, e.g., -O instead of -O2. MAKE = make # which "make" to use CFLAGS = -O2 # options, e.g. for optimisation or ANSI compilation. # HP/UX cc needs CFLAGS = -Aa (HP/UX 9) or -Ae (HP/UX 10) # BeOS needs CFLAGS = -O2 -Wl,-L/boot/home/config/lib # BS2000/OSD needs CFLAGS = -XLLML -XLLMK # NeXTSTEP needs CFLAGS = -O2 -pipe -no-precomp DEFS = # any combination of -DNOPIPES -DNODNS -DNODIRENT -DNOGLOB ... # ... -DNOOPEN -DNOFOLLOW -DNOALARM -DNOGRAPHICS -DNOGMTIME ... # ... -DEBCDIC -DUSE_PLAIN_SETJMP -DHAVE_GD -DHAVE_PCRE ... # ... -DNEED_STRCMP -DNEED_MEMMOVE -DNEED_STRTOUL ... # ... -DNEED_DIFFTIME -DHAVE_ADDR_T -DNEED_FLOATINGPOINT_H # All the options are explained at the bottom of this file. # # Solaris 2 (SunOS 5+) might need DEFS = -DNEED_STRCMP # SunOS 4 usually needs... # DEFS = -DNEED_MEMMOVE -DNEED_STRTOUL -DNEED_DIFFTIME -DNEED_FLOATINGPOINT_H # 64-bit Solaris needs -DHAVE_ADDR_T # DYNIX/ptx needs -D_SOCKET_VERSION=11 # MPE/iX needs -D_POSIX_SOURCE -D_SOCKET_SOURCE # OS = OSX # Operating system: UNIX, DOS, WIN32, MAC, OS2, OSX, VMS
Save the file.
Type the following command: sudo make (supply an admin password when prompted)
Depending on the speed of your machine this step might take a few minutes.
When complete you will see a warning message (see Figure 2.). This is normal, and Analog has been built.
/usr/bin/ld: warning unused multiple definitions of symbol _warn utils.o definition of _warn in section (__TEXT,__text) /usr/lib/libm.dylib(err.o) unused definition of _warn
To confirm that is has been built, go back up one level and do an “ls” You should see analog in the directory.
You can place Analog anywhere you would like on the system but the standard location is /usr/local/bin.
sudo mkdir /usr/local/bin/analog sudo cp analog /usr/local/bin/analog sudo cp –r images /usr/local/bin/analog/images
The images directory contains the images used for the reports. You want it here so you can share one copy of these files with all of your websites. To do that we will add an alias directive to Apache.
sudo vi /etc/httpd/httpd.conf
Find the following line:
Alias /icons/ "/usr/share/httpd/icons/"
Add this line immediately after and save the file:
Alias /analog_images/ "/usr/local/bin/analog/images/"
Restart Apache: sudo apachectl restart.
Analog is now installed and ready to be configured.
Step 2: Configuring Analog
Analog has a very large number of commands. I will only cover a few, the ones I am using in my configuration files. You can place the configuration files in any location you like. I manage a large number of sites so I like to keep all of the config files in a single location. You can also place them in the individual site folders. I do recommend that you create a folder in your site folder to store the output of your Analog runs (I call mine reports)
There are two config files to be concerned with. One is called analog.cfg and if used will live in /usr/local/bin/analog with the executable. Analog will always look for this file first and apply all of the commands in it to any run unless you tell it not to with a “-G” on the command line.
The other config file is the one that goes in your site folder or wherever you decide to put it. The extension of .cfg is not magic. You can call the file anything you want. Figure 3 shows one of my config files. The line numbers are not in the file. They are just here for reference.
1 APACHELOGFORMAT (%h %l %u %t \"%r\"
%>s %b \"%{Referer}i\" \"%{User-Agent}i\")
2 LOGFORMAT COMBINED
3 LOGFORMAT COMMON
4 LOGFILE /Volumes/Data/www/your_domain/logs/access_log*
5 OUTFILE /Volumes/Data/www/your_domain/stats.html
6 HOSTNAME "your_hostname"
7 HOSTURL "http://www.your_domain/"
8 IMAGEDIR "http://www.your_domain/analog_images/"
9 HOSTEXCLUDE xx.xx.xx.xx
10 HOSTEXCLUDE *.your_domain
11 DNSFILE dnscache
12 DNS WRITE
13 BROWSERREP ON
14 BROWSERSUM ON
Let’s go through the config file and cover the basic commands:
Lines 1 – 3 define the log file format. If you have made no changes to Apple’s defaults your logfile format will be: “%h %l %u %t \"%r\" %>s %b"
Line 4 tells Analog where to look for the logs. Note the wildcard. If you tell Apache to roll your logfiles you will need this as they will all have unique names.
Line 5 tells Analog where to place the output file as well as the name of the file. Make sure you get the permissions correct so the Analog process can write to this directory.
Line 6 is used for display purposes only and can be anything you like
Line 7 is used as the link for HOSTNAME when displayed on the results page.
Line 8 points to the images, using the alias we set up earlier.
Lines 9 & 10 tell Analog to ignore these domains, either by name or by IP address. You would usually want to put your own domain and IP addresses of developers here so your hitting the site hundreds of times a day does not skew the report.
Line 11 is used for analog to cache DNS lookups. DNS lookups are very time consuming. By caching them, Analog will look in this file first before going out on the Internet. Note: According to Analog’s bugs page, there is a bug in Mac OS X' internal libraries that causes crashes if DNS lookups are enabled. If you see failures when running Analog, comment out lines 11 and 12 and re-run; you will lose the nice IP to hostname resolution, but won’t lose your reports altogether.
Line 12 tells Analog to write the DNS lookup info to the cache file.
Line 13 & 14 turn on broswer reporting. This will not work with Apple’s standard log format, which is rather anemic in the information it provides.
Step 3: Now that is all configured, what do I do to make it run?
The basic command for Analog looks like this:
/usr/local/bin/analog/analog –G +gconfigfile
Here, I tell Analog to ignore the global config file (analog.cfg) and only use my configuration file. There is no space between the +g and the config file name. That is not a typo.
The final step would be to add an entry to the root crontab to run this as often as you feel you need to. Mine runs daily at midnight.
Reference Sources and help:
The Analog Help mailing list: http://www.analog.cx/docs/mailing.html
Analog online documentation: http://www.analog.cx/docs/indx.html
Analog online Quick Reference: http://www.analog.cx/docs/quickref.html