Adding extra reports using the ExtraSection feature

The AWStats ExtraSection features are powerfull setup options to allow you to add your own report not provided by default with AWStats. You can use it to build special reports, like number of sales for a particular product, marketing reports, counting for a particular user or agent, etc...

Explanation on how to add/edit an Extra report in your config file
Take a look inside the AWStats config file to find the following part:
#-----------------------------------------------------------------------------
# EXTRA SECTIONS
#-----------------------------------------------------------------------------

Read all explanation in config file after this point, they will explain you how to add an Extra report by adding an ExtraSection configuration in your config file,
or just click here to jump to a copy of this explanation.

Following examples are precious tutorials...

Some examples of ExtraSection setup you can follow to build your own personalized reports:

Example 1: Tracking Product orders

Example 2: Tracking Bugzilla most frequently viewed bugs

Example 3: Tracking Exit clicks

Example 4: Tracking aborted download

Example 5: Tracking most requested domain aliases

Example 6: List of top level 2 path under a directory /mydir

Example 1: Tracking Product orders

Image your web site is an e-store that sells 80 different products. Each of them has an id. Imagine each time, someone make an order for product 49, the order.cgi script or order2.cgi script is called with, in URL query parameter, the id of the product, meanings that you get in your log file a hit that looks like this:

GET /cgi-bin/order.cgi?productid=49&session=A0B1C2

So this is how you need to setup your ExtraSection to track your product orders:

ExtraSectionName1="Product orders"
ExtraSectionCodeFilter1="200 304"
ExtraSectionCondition1="URL,\/cgi\-bin\/order\.cgi|URL,\/cgi\-bin\/order2\.cgi"
ExtraSectionFirstColumnTitle1="Product ID"
ExtraSectionFirstColumnValues1="QUERY_STRING,productid=([^&]+)"
ExtraSectionFirstColumnFormat1="%s"
ExtraSectionStatTypes1=PL
ExtraSectionAddAverageRow1=0
ExtraSectionAddSumRow1=1
MaxNbOfExtra1=100
MinHitExtra1=1

Example 2: Tracking Bugzilla most frequently viewed bugs

This is an example on how to setup your ExtraSection:

ExtraSectionName1="Bugzilla: Most frequently viewed bugs"
ExtraSectionCodeFilter1="200 304"
ExtraSectionCondition1="URL,\/bugzilla\/show_bug\.cgi"
ExtraSectionFirstColumnTitle1="Bug ID"
ExtraSectionFirstColumnValues1="QUERY_STRING,id=([^&]+)"
ExtraSectionFirstColumnFormat1="<a href='/bugzilla/show_bug.cgi?id=%s' target=new>%s</a>"
ExtraSectionStatTypes1=PL
ExtraSectionAddAverageRow1=0
ExtraSectionAddSumRow1=1
MaxNbOfExtra1=500
MinHitExtra1=1

Example 3: Tracking Exit clicks

AWStats shows you naturally the exit pages. However, you don't know where you visitor go after exiting your site since clicking on a link that point to an external link will log the viewed page on the external server and not on yours. If you want to track this, you can, using the ExtraSection and the awredir.pl tool (provided with AWStats).
This tools must be used as a CGI wrapper. When called on 'A HREF' link, it returns to browser a redirector to tell it to show the required page. So, to use this script, you must replace HTML href tags that points to external web sites onto your HTML pages from

For your web visitor, there is no difference. However this allow you to track clicks done on links onto your web pages that point to external web sites, because an entry will be seen in your own server log like this record:

80.1.2.3 - - [01/Jan/2001:16:00:00 -0300] "GET /cgi-bin/awredir.pl?url=https://externalsite/pagelinked HTTP/1.1" 302 70476 "https://yoursite/pagewithlink.html" "FireBird/0.7"

Then, you can add in AWStats a chart to track all call to awredir.pl with keys values taken from the "url=" parameter. You will get an independant chart, counting all external pages viewed by your visitor after exiting your site.
To have this chart, this is how you must setup your ExtraSection:

ExtraSectionName1="Redirected Hit"
ExtraSectionCodeFilter1="302"
ExtraSectionCondition1="URL,\/cgi\-bin\/awredir\.pl"
ExtraSectionFirstColumnTitle1="Url"
ExtraSectionFirstColumnValues1="QUERY_STRING,url=([^&]+)"
ExtraSectionStatTypes1=HL
MaxNbOfExtra1=500
MinHitExtra1=1
ExtraSectionAddSumRow1=1

Example 4: Tracking aborted download

Aborted downloads are reported in a log file by a 206 error, so this is how you need to setup your ExtraSection to add a chart for a such tracking:

ExtraSectionName1="List of aborted download"
ExtraSectionCodeFilter1="206"
ExtraSectionCondition1=""
ExtraSectionFirstColumnTitle1="URL"
ExtraSectionFirstColumnValues1="URL,(.*)"
ExtraSectionStatTypes1=PHB
MaxNbOfExtra1=100
MinHitExtra1=1

Example 5: Tracking most requested domain aliases

You have one website, but this web site has several domains named (for example the same site domain.com can be reached with urls domain.com,www.domain.com,www.otherdomainname.com,www.againadomainname.org,...). You want to know which domain alias is the most used.

The first thing to do is to be sure the domain alias is recorded inside your log file. If you use Apache, you must use a personalized Apache log file that contains the %V tag. For example you can add in your Apache httpd.conf file a new Apache log format (This is the Apache directive, not AWStats, to define an Apache log format that contains the virtual domain):

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %V" combinedv

Then check that your Apache CustomLog directives are defined like this:

CustomLog pathtoyourlog/yourlog.log combinedv

After restarting Apache, your log format should look like this

66.130.77.181 - - [09/Aug/2004:03:01:05 +0200] "GET /index.php HTTP/1.1" 200 1473 "-" "Firefox 1.0" www.otherdomainname.com

When your web server log file contains the domain alias, you can now setup AWStats to use it. For this use a personalised AWStats log format and use the %extra1 tag at the same position where the domain alias is. For example, for your combinedv Apache log format, we will use:

LogFormat="%host %other %logname %time1 %methodurl %code %bytesd %refererquot %uaquot %extra1"

Every tag defined by name extraZ (Z is a number, you can use as many tags as you need) can be used in any ExtraSection to extract the parameter. You can use the name extraZ as a criteria in the ExtraSectionFirstColumnValuesX parameter (X is number of the extra report, you can add as many report as you need) to tell AWStats to use value in log file at the place of the tag, as the key for your report. For example:

ExtraSectionName1="Domains aliases"
ExtraSectionCodeFilter1="200 304"
ExtraSectionCondition1=""
ExtraSectionFirstColumnTitle1="Domain alias"
ExtraSectionFirstColumnValues1="extra1,([^&]+)"
ExtraSectionFirstColumnFormat1="%s"
ExtraSectionStatTypes1=HL
ExtraSectionAddAverageRow1=0
ExtraSectionAddSumRow1=1
MaxNbOfExtra1=20
MinHitExtra1=1

And result will be:

Domains aliases

Domain alias	Hits	Last visit
www.domain.com	1757131	08 August 2004 - 13:01
www.otherdomainname.com	98518	08 August 2004 - 12:54
domain.com	19107	08 August 2004 - 12:42
www.againadomainname.org	7609	08 August 2004 - 11:56
Total	1883986

Example 6: List of top level 2 path under a directory /mydir

So this is how you need to setup your ExtraSection to add a chart for such a tracking:

ExtraSectionName1="List of top level 2 path under /mydir"
ExtraSectionCodeFilter1="200 304"
ExtraSectionCondition1="URL,^\/mydir\/.*"
ExtraSectionFirstColumnTitle1="Directory name"
ExtraSectionFirstColumnValues1="URL,^\/mydir\/([\w]+)\/"
ExtraSectionStatTypes1=PHK
MaxNbOfExtra1=50
MinHitExtra1=1

There is a lot of other possible use for Extra Sections ...

The following explanation is same than the one found in AWStats config file:

#-----------------------------------------------------------------------------
# EXTRA SECTIONS
#-----------------------------------------------------------------------------
# You can define your own charts, you choose here what are rows and columns
# keys. This feature is particularly usefull for marketing purpose, tracking
# products orders for example.
# For this, edit all parameters of Extra section. Each set of parameter is a
# different chart. For several charts, duplicate section changing the number.
# Note: Each Extra section reduces AWStats speed by 8%.
#
# WARNING: A wrong setup of Extra section might result in too large arrays
# that will consume all your memory, making AWStats unusable after several
# updates, so be sure to setup it correctly.
# In most cases, you don't need this feature.
#
# ExtraSectionNameX is title of your personalized chart.
# ExtraSectionCodeFilterX is list of codes the record code field must match.
# Put an empty string for no test on code.
# ExtraSectionConditionX are conditions you can use to count or not the hit,
# Use one of the field condition
# (URL,URLWITHQUERY,QUERY_STRING,REFERER,UA,HOSTINLOG,HOST,VHOST,extraX)
# and a regex to match, after a coma. Use "||" for "OR".
# ExtraSectionFirstColumnTitleX is the first column title of the chart.
# ExtraSectionFirstColumnValuesX is a string to tell AWStats which field to
# extract value from
# (URL,URLWITHQUERY,QUERY_STRING,REFERER,UA,HOSTINLOG,HOST,VHOST,extraX)
# and how to extract the value (using regex syntax). Each different value
# found will appear in first column of report on a different row. Be sure
# that list of different possible values will not grow indefinitely.
# ExtraSectionFirstColumnFormatX is the string used to write value.
# ExtraSectionStatTypesX are things you want to count. You can use standard
# code letters (P for pages,H for hits,B for bandwidth,L for last access).
# ExtraSectionAddAverageRowX add a row at bottom of chart with average values.
# ExtraSectionAddSumRowX add a row at bottom of chart with sum values.
# MaxNbOfExtraX is maximum number of rows shown in chart.
# MinHitExtraX is minimum number of hits required to be shown in chart.

Warning: the ExtraSectionConditionX MUST use regex values since AWStats 6.0.
ExtraSectionFirstColumnValuesX also need REGEX value for all AWStats versions.
Return to examples for examples on syntax use.

Article written by Laurent Destailleur.

Follow @awstats_project