Some things to think about when changing AWStats.

AWStats is a large and fairly complex system. The following description should be considered as only the briefest introduction to how that system works and what you may need to change to amend the system to your own needs.

As always, don't underestimate the time it will take to “get your head around” the software. In particular, you will need to understand clearly how awstats.pl reads in and parses the data in the web server files, all of which is done using one or more levels of indirection. Until you understand this fully, any changes could have completely unexpected consequences.

Note carefully that a surprisingly large proportion of the operation and appearance of AWStats may be altered without making any code changes at all. Getting to grips with the format and potentials of the configuration file (%AWSTATSROOT%\wwwroot\cgi-bin\awstats.conf) may be the best time investment you can make, when you wish to change how AWStats appears to work. Only after doing that and exhausting all the possibilities should you consider changing the script itself.

Directory Layout

A typical Windows installation tree:

C:
 |
  -- Apache2.2
      |
       --AWStats
      |   |
      |    -- docs            HTML documentation for the project
      |   |
      |    -- ServerLogs         Default log location (data source)
      |   |
      |    -- tools              Special purpose AWStats scripts 
      |   |    |
      |   |     -- webmin        Web administration tool for AWStats
      |   |    |
      |   |     -- xslt          Demonstration files for report building
      |   |
      |    -- wwwroot
      |        |
      |         -- cgi-bin       AWStats main script & configuration files
      |        |    |
      |        |     -- lang     Static text for generated reports
      |        |    |
      |        |     -- lib      Perl packages (AWStats components)
      |        |    |
      |        |     -- plugins  Optional AWStats components
      |        |
      |         -- classes       Java support files
      |        |
      |         -- css           Style sheets
      |        |
      |         -- icon          Image files for generated web pages
      |        |
      |         -- js            Javascript enhancements to AWStata
      |
       --- htdocs                Login pages and generated report pages

Setting Static Text

The basic text for the reports is defined by one of the files in the lang directory. In theory, the language is chosen according to processing in the awstats.pl sub Read_Language_Data() and the default setting is awstats-en.txt. To force a particular language setting, recode this sub to hard code the required file. If this file cannot be loaded, add some new code that causes the script to die.

Each string is set to a messagennn variable, where nnn is a number from 0 to 172. Additional messages for the report should be added with numbers above the existing set, while existing text can be changed globally by replacing the string value for the message. For example, you might do something like this:

 Message  Old Text                     New Text
 -------  ---------------------------  --------------------------------  
 10       Number of visits             Total Streams Delivered
 56       Pages                        Live Streams Delivered
 57       Hits                         VoD Streams Delivered

Changing Column Valuations

Calculations and display creation are all done in the mainline code of awstats.pl. Note that there are tens of thousands of statements in this script, many concatenated onto a single line.

A (partial) guide to awstat.pl may be found in AWStats General Operation

The least difficult method of making a change is probably to begin by identifying the message that introduces the value, find where the associated value is set on the page and then work backwards from there. (The message variable will always appear as $message[nnn] where nnn will match the message number value as described in the section Setting Static Text).

Please consider that a value may be set up in several places! Values are not, generally, carried forward but re-calculated for each report section, so that sections may be removed or amended independently.

Display variable Setting

There are a limited number of display variables. Here are some of the most important ones:

 Variable        Set by
 --------------  ----------------------------------------------------
 $TotalPages     $TotalPages+=$MonthPages{$YearRequired.$monthix}||0;
 $MonthPages     $MonthPages{$year.$month}+=$monthpages;
 $monthpages     $monthpages+=int($field[1]);
 $field[1]       @field=split(/\s+/,($readxml?XMLDecodeFromHisto($_):$_));
 $_              $_=<HISTORY>;
 $TotalHits      $TotalHits+=$MonthHits{$YearRequired.$monthix}||0;
 $MonthHits      $MonthHits{$year.$month}+=$monthhits;
 $monthhits      $monthhits+=int($field[2]);