Changes

These WWW statistics are still in beta-test, and are constantly being changed. This is where you read about the latest changes, news, updates, whatever.

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 :)

Intro

First, please note that this functionality is only available on xs4all, and only for xs4all accounts.

.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.

Feedback

These WWW statistics are still in beta-test. There are probably still a few bugs that need to be ironed out.

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 (johnpc@xs4all.nl) about it!

Special tags

Please note that there is a list available of things recently changed or added.

<StatFile>

This indicates the start of a generated file. The file continues until a closing </StatFile> or until the end of file. You must have this in your .stats file. Everything that is not inside a <StatFile> </StatFile> construct is simply ignored.

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:

mode=octal number: Specifies the access mode of the file, in octal.
site=site name: When you serve more than one site from the same directory, for example if you have a homepage on your own domain, the .stats file serves both domains. In this case, you have to include a site= parameter in the <StatFile> tag, to distinguish one site from another.
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.

Example

<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.

<Stats>

<Stats> tags are used to include the actual statistics in your files. These tags expand to a number, a sorted list or URLs, or to a graph displaying the number of accesses (when image/gif support is added).

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.

<Stats MonthHits>: Returns the number of hits this month.
<Stats MonthTraffic>: Returns the traffic this month.
<Stats TotalHits>: Returns the total number of hits since the beginning of the stats.
<Stats TotalTraffic>: Returns the total traffic since the beginning of the stats.
<Stats TopURL>: Returns a sorted list of all URLs accessed.
<Stats TopDomain>: Returns a sorted list of all domains that have accessed.
<Stats LogDate>: Returns the date until when the logs have been processed.
<Stats LogMonth>: Returns the current month and year.
<Stats PerDay>: Returns a list of hits and/or traffic per day for this month.

<Stats MonthHits>

This tag returns the number of hits so far this month on all of your pages, or on the specified pages.

Optional arguments include:

url=filespec

Return the hits for only the specified filespec, which is either a file relative to your ~/WWW/ or DocumentRoot directory, or a full-blown URL including http:// and the hostname. Make sure you write the hostname using all lowercase. This is not case insensitive, as you might expect.

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.

Example

My homepage has been accessed <Stats MonthHits url= > times this month.

<Stats MonthTraffic>

This tag returns the traffic generated so far this month on all of your pages, or on the specified pages.

Optional arguments include:

url=filespec: Return the traffic for only the specified filespec, which is either a file relative to your ~/WWW/ or DocumentRoot directory, or a full-blown URL including http:// and the hostname. Make sure you write the hostname using all lowercase. This is not case insensitive, as you might expect.
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.
inK: Return the traffic in Kbytes (1024 byte unites) instead of in bytes, as it is by default.
inM: Return the traffic in Mbytes (1048576 byte units) instead of in bytes.
format=formatspec: Specifies the format in which the number should be returned. The default format is ".0". This is the format that is used by the C library printf() function, for formatting floating point numbers. The number is returned as if through a printf("%formatspecf", traffic)

Example

Total traffic this month: <Stats MonthTraffic inM format=.2>Mbyte

<Stats TotalHits>

This tag returns the total number of hits on all of your pages or on the specified pages, since the web statistics started.

Optional parameters are exactly the same as those for <Stats MonthHits>

Example

I've had <Stats TotalHits> accesses to my pages since the epoch!

<Stats TotalTraffic>

This tag returns the total traffic generated by all of your pages or by the specified pages, since the web statistics started.

Optional parameters are exactly the same as those for <Stats MonthTraffic>

Example

This nice picture of myself has wasted at least <Stats TotalTraffic url=pics/me_shower.jpg inM format=.1> Mbytes of traffic.

<Stats TopURL>

This tag returns a sorted list of all URLs below your ~/WWW/ or DocumentRoot directory.

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:

ByHits: Sorts the URLs by number of hits. This is the default.
ByTraffic: Sorts the URLs by amount of generated traffic.
Top=max: Only displays the top max URLs. Default is to display the top 50.
Numbered: This will index each URL with a sequence number, starting at 1.
UnNumbered: This means no numbers in front of the URLs. This is the default.
WithHits: When sorting on traffic, also include the number of hits. Note that when sorting on hits, the number of hits is automatically included.
WithTraffic: When sorting on hits, also include the generated traffic. Note that when sorting on traffic, the generated traffic is automatically included.

Example

<hr>
<Stats TopURL ByHits Numbered WithTraffic>
<hr>

<Stats TopDomain>

This tag returns a sorted list of all domains that have accessed your pages.

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>

Example

The following domains have showed interest in my pages:
<Stats TopDomain>

<Stats LogDate>

This tag returns the date until which the logfiles have been processed, so the information that you give is valid upto that point. Format is as it appears in the NCSA logfile, eg. 14/Sep/1995:01:29:31 +0200

Example

These statistics have last been updated on: <Stats LogDate>

<Stats LogMonth>

This tag returns the current month and year in exactly the same format as the string "$month" expands in <StatFile ...> tags. This is useful for refering to another statistics file, while also keeping a separate file for each month.

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 :).

Example

<Stats PerDay>

This tag returns a list of hits and/or traffic generated per day. Note that this counts hits to all of your pages, not only to the homepage or something. It is not possible to restrict the hits or traffic to certain URLs.

Optional arguments include:

WithHits: Include the hits. This is the default if you don't specify anything.
WithTraffic: Include the traffic generated, in Kbyte.

Example

Hits per day:<p>
<Stats PerDay>

Complete Example

The following file is an example .stats file. I use it to measure the traffic from my homepage. You can look at the result of this.

You can copy this file and use it for your own statistics. Simply install it as .stats in your ~/WWW/ or DocumentRoot directory.

Example code:

<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. My page has generated <Stats MonthTraffic inM format=.3>Mbyte traffic so far this month. Statistics are valid from the start of this month until <Stats LogDate>. <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: <Stats TopDomain ByTraffic WithHits UnNumbered top=100> <hr> Number of hits per day: <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>