Tips on troubleshooting Urchin processing problems

If your reports are provided for you by your hosting company, ISP, or web administrator, you will have to contact the responsible party regarding your Urchin reports. Urchin Software Corp. does not directly run or manage Urchin reporting in any way. Our software is simply used by other companies to provide web analytics reports for their end users or customers.

If you configure and manage your own reports, please continue reading for additional tips on troubleshooting Urchin processing problems...

The most common causes of Urchin failing to update are due to one of the following:

  1. The Urchin Scheduler is not running.
  2. There is a problem with the webserver logfile location or configuration.
  3. There is a problem with the Urchin database.

Urchin Scheduler

Unless you manually run Urchin to update your reports, they are updated according to the Urchin Scheduler configuration. The Urchin Scheduler daemon must be running for the reports to update on time. To check the status of the scheduler, you'll need to open a command shell to the Urchin server and change directory to the "bin" directory of the Urchin distribution. From there, run the following command to check the status:

  ./urchinctl status  (Note: omit the "./" for Windows
systems)
If either the Scheduler or the Urchinwebd are not running, you can restart them as follows:
  ./urchinctl start
Once the scheduler is running again, you may wait for Urchin to update according to its normal schedule or manually update it by selecting the "Run Now" option from the Urchin Administrative GUI.

Log File Configuration

If the location of the log file changes or if the format of the log file changes, Urchin may stop updating the reports. To determine if this is happening, scroll down to the section in this article titled "Task History Inspection." to look for related errors.

If the log format does not match one of Urchin's automatically recognized formats, or if you have selected one format, but the logs are written in a different format, Urchin will not be able to read them and create report data properly. The following article contains full details on which formats Urchin will read and how to configure your server to write logs in those formats: Logging - Apache and IIS.

Database Problem

Urchin stores data on a per-profile monthly databases in the data/reports directory of the Urchin distribution. If the Urchin databases are corrupt or locked for any reason, the reports will stop updating for the affected profile. To determine if this has happened, see the following section titled "Task History Inspection."

Task History Inspection

Urchin keeps a record of every attempt to process logs for every profile. If you suspect there may be a problem with the processing, these logs will often provide information that points to the root of the problem.

There are two ways to access this information:

  1. Open the Urchin Configuration GUI and select the following window: Configuration -> Scheduler -> Task History. From this view you'll see a Status column. Each item in the "Status" column is a clickable link. The link will open a window that displays the process status when Urchin attempted to process the log file for that profile. They are listed by date/time/profile as indicated in the remaining columns in this window. Click "Next" if necessary to find the profile and date you are looking for.
  2. These same files are available on the server Urchin is running on. They are organized by profile so that each profile has a unique directory with all the Task History files contained within. The path to the profile directories is ~urchin/data/history/"profile-name" where "profile-name" represents the profile directory. The files are not date named but they are in order so that the oldest file is the first history file and the last file in the list is the most recent history file with the latest process data.

The data in these files can be broken down as follows:

------------------------------------------------------
Urchin 5.7.02 (freebsd4x) starting: 20040217 23:50:02
------------------------------------------------------

Lists Urchin version, Operating system and the start date/time of the job

Processing profile: your-domain.com (on your-server.25624)
Lists the Profile name, server name and PID

[23:50:04] Logfile: /usr/local/etc/httpd/vhosts/logs/access_log
Displays the time the log was opened for processing and the full path to the file

data lines: 0 (0%) (skipping 384518 bytes)
(When applicable) Number of data lines that have already been processed by Urchin
data lines: 11482 (100%)
Number of 'unprocessed' data lines
data hits: 10320
Number of data lines that were actually processed (Urchin filters may affect this value)
data proc: 89518.08 KB in 00:00:52 (0.711 MB/sec)
Time taken to process 'n' bytes of data. If under .05 seconds, will be displayed as zero
data range: 2004-02-17 00:11 (GMT) - 2004-02-17 23:48 (GMT)
Total date range of all hits processed

[23:50:07] Backing up database files for 200402: /usr/local/urchin5/data/reports/your-domain.com/200402-backup- 20040217235007.zip
Creating failsafe backup for Profile data. Backup covers all data for the month displayed (Feb 2004 in this case)

Removing outdated backup for 200402: /usr/local/urchin5/data/reports/your-domain.com/200402-backup- 20040215235022.zip
Removing the previous failsafe backup which was created during the previous log processing job

------------------------------------------------------
Urchin 5.7.02 (freebsd4x) finishing: 20040217 23:50:07
------------------------------------------------------