NEW! there's now a very readable statistics FAQ online! (In dutch)
(Noot: deze beschrijving is dan wel in het Engels, maar ik ben gewoon een Nederlander, Emailtjes mag je dus ook in het Nederlands sturen :)
.stats files are used to generate custom WWW access statistics. Put the .stats file in your ~/WWW/ directory, or in de DocumentRoot for your server. Each .stats file is capable of generating multiple files, either HTML files or plain text files, or (in the future) GIF pictures.
Please note that the .stats files cannot provide "live" counters. There is a process (boringly called wwwstat), that processes the WWW access logs, combines it into a database, parses all .stats files, and writes out the resulting files. Therefore, counters, traffic measurements etc will only be updated whenever the wwwstat program runs.
If you don't like to read through all this, but instead start experimenting with a simple example, there is one at the bottom of this page.
Read this if you simply want a counter on your homepage.
The format of .stats files closely follows the SGML standard. A detailed description of the format of these files can be found in the rest of this document. The tags described here are case insensitive, just like other HTML tags, except where otherwise stated. Most notably, filenames are never case insensitive.
When the server detects an error in your .stats file, and it cannot continue because of this error, it will produce a .stats.err file in the same directory as the .stats file.
The wwwstat program is currently automatically being run every six hours. The exact time might vary a bit as I'm still modifying the program. So whenever you change your .stats file, you will have to wait until the next run of the program to see the changes. (See also the changes page).
This is also why, when you first install a .stats file, you will have to wait a while before the results are visible.
Also, I really would like suggestions for improvement. Things that will definately come in the future are: GIF pictures, PerHour average hits and traffic, and lots more. See also the suggested improvements. We are also considering making your own part of the httpd.access file available. Some extensions will only be available to commercial websites, not to homepages in general (most notably having your own part of the httpd.access file).
If you have any suggestions, then please send mail to me
There can be multiple <StatFile> .. </StatFile> sections in your .stats file. Each section is processed independently, producing as many statistics files as you like.
Everything between the <StatFile> </StatFile> tags is copied to the specified file, except for the special <Stats> tag. All other tags are passed unchanged, so you can put whatever HTML constructs in your files as you like. The <Stats> tag is described below.
The <StatFile> tag must have at least one argument directly following it, which is the filename that is written. If no absolute path is specified, the file is considered to be relative to your ~/WWW/ directory or DocumentRoot. It can be an absolute filename, or it can start with ~username/ or ~/, to put it in the appropriate users' home directory.
Further, any occurance of the string $month in the filename, is replaced by the current month (three letter abbreviation), followed by the year, for example: Aug1995. You should use this to make separate statistics files for each month. If you want to refer to such files, see the <Stats LogMonth> tag.
Note that the extension of the generated statistics files is important. From the extension, the Mime type of the file is determined, and different action is taken for different Mime types. Note that image/gif is not implemented yet, but will be in the future. text/html type files generate HTML files, with markup where appropriate. text/plain type files contain only plain ASCII.
Other arguments that can be included in the <StatFile> tag are:
For example, to specify that you want the statistics only for your
homepage, use this:
<StatFile homepagestats.html site=www.xs4all.nl/~username>
To get statistics for your site, use:
<StatFile domainstats.html site=www.yourdomain.nl>
If you don't include the site= parameter, your .stats.err file will log a warning saying "filename overwrites statistics for www.yourdomain.nl with www.xs4all.nl/~username" or something similar...
Note that these arguments should always come after the filename.
<StatFile statistics.html mode=644> <Title>Example statistics file</Title> Just testing. </StatFile>This example would write out a file "statistics.html" in your WWW or documentroot directory, with file mode 644. The second and third lines in the example are literally copied into the file, so this HTML file has a title of "Example statistics file", and it contains the single sentence "Just testing.". The fourth line terminates the example.
Each <Stats> tag has one obligatory argument: the type of statistics that is requested. Several optional arguments may follow the first one, depending on the type. The following table lists the available types, along with a short description. Each type is further explained in the sections below.
Optional arguments include:
If you include multiple url= options, the hits for these URLs will be summed.
You should not include a trailing index.html file, as this is equivalent to retrieving the directory, and the statistics program simplifies this by using only the directory, not the index.html file. As a result of this, if you leave filespec empty, ie. you write url= without any further argument, you get the number of hits on your homepage.
Optional arguments include:
If you include multiple url= options, the traffic for these URLs will be summed. You should not include a trailing index.html file, as this is equivalent to retrieving the directory, and the statistics program simplifies this by using only the directory, not the index.html file. As a result of this, if you leave filespec empty, ie. you write url= without any further argument, you get the amount of traffic generated by your homepage.
Optional parameters are exactly the same as those for <Stats MonthHits>
Optional parameters are exactly the same as those for <Stats MonthTraffic>
When generating a text/html type file, HTML tags are automatically added to make this into a table (using <pre>). Also, all URLs will be references to themselves, using <a href="...">. When writing text/plain files, no such tags are added.
Optional arguments include:
<hr> <Stats TopURL ByHits Numbered WithTraffic> <hr>
The same comments that apply to <Stats TopURL> regarding adding HTML tags to text/html files also apply here.
Additionally, optional arguments are exactly the same as those for <Stats TopURL>
The following domains have showed interest in my pages: <Stats TopDomain>
These statistics have last been updated on: <Stats LogDate>
Note that you will usually use this tag within another tag. Although this doesn't look like valid SGML, it really isn't a problem, since the .stats files are never looked at by a browser (unless you specifically point your browser to a .stats file, which isn't very useful).
The wwwstat process does look at the .stats files, but it can handle nested tags, don't worry :).
See also the <a href="domainstats.<Stats LogMonth>.html"> domain accesses</a> </StatFile> <StatFile domainstats.$month.html> <Stats TopDomain>
Optional arguments include:
Hits per day:<p> <Stats PerDay>
You can copy this file and use it for your own statistics. Simply install it as .stats in your ~/WWW/ or DocumentRoot directory.
<StatFile statistics.html> <html><head> <title>Homepage usage statistics</title> </head><body> I've had <Stats TotalHits url= > accesses to my homepage since the epoch.<p> My page has generated <Stats MonthTraffic inM format=.3>Mbyte traffic so far this month.<p> Statistics are valid from the start of this month until <Stats LogDate>.<p> <hr> Top of all URL's referenced from my pages, sorted by number of hits, for this month: <Stats TopURL WithTraffic Numbered> <hr> I've had visitors to my pages from these domains:<p> <Stats TopDomain ByTraffic WithHits UnNumbered top=100> <hr> Number of hits per day:<p> <Stats PerDay WithHits WithTraffic> <hr> Look at <a href="http://www.xs4all.nl/~johnpc/dotstats.html">the description of <tt>.stats</tt> files</a> if you want to have these same nice usage statistics. </body></html> </StatFile>