Site Statistics
Introduction
Statistics of visits to pages in a web can be generated manually or automatically, on a per-web basis. Statistics are compiled as a running total for each month.They include totals for Topic Views, Topic Saves, Attachment Uploads, Most Popular Topics with number of views, and Top Contributors showing total of saves and attachment uploads. Statistics from previous months are saved, and a new row is written to the table at the beginning of each month.
- You can create a WebStatistics link using
%STATISTICSTOPIC%
Statistics are compiled by a script that processes the Foswiki event log. The script can be run two ways:
- Manually, by an authorized user from a browser URL
- Automatically by a shell script, usually run as a
cron
job
Manually running statistics
The following form can be used to run statistics and create the WebStatistics topics for selected or all webs.
Note: The current user -
WikiGuest must have access rights to read/write the WebStatistics topics, and if missing, must have authority to create the WebStatistics in the selected webs.
Controlling access to the statistics script
By default, the statistics script may be run by anyone, however the user must have
CHANGE
permission on the WebStatistics topic. Statistics generation can create a significant workload on the server. In order to further restrict statistics generation:
- Add
statistics
to the configure Security and Authentication
tab, Login
sub-tab.(This is now the default on Foswiki 1.1.4). This is required to prevent unauthenticated guest users from running statistics
.
- If using Apache authentication, be sure to add it to the Apache configuration.
- If desired, create a Group for users that should be permitted to run the statistics script, or use the AdminGroup.
- Visit configure
Logging and Statistics
tab, and set {Stats}{StatisticsGroup}
to the group permitted to run statistics.
- Note: Regardless of this setting, members of the AdminGroup can always run statistics.
Configuring for automatic operation
You can automatically generate usage statistics for all webs. To enable this:
- By default, the WebStatistics topic must be present in all webs where you want to have statistics. See below for how to create the WebStatistics topic.
- Call the
bin/statistics
script from a cron job, once a day is recommended. This will update the WebStatistics topics in all top level webs. (Sub-webs are not processed by default).
- Caution: The script must run as the same user as the Web Server CGI scripts. This varies by platform, but is typically
apache
, www
. or nobody
on many systems. Verify this before running statistics from the command line or cron. If the ownership of critical files is changed, it can render the Foswiki server inoperable.
- Example crontab entry to process all webs and subwebs containing a WebStatistics topic:
0 0 * * * (cd /path/to/bin; ./statistics -subwebs 1 >/dev/null 2>&1)
- This crontab entry should be installed for the web server user, not
root
!
There is a workaround in case you can't run the script as the CGI user. Use the
curl
or
wget
tools available on most distributions. These two examples perform the same function using curl and wget in the crontab. You should only use one of them.
0 0 * * * (curl -F webs=Sandbox -F subwebs=1 your.host.com/bin/statistics >/dev/null 2>&1)
0 0 * * * (wget --post-data 'webs=Sandbox&subwebs=1' -O - your.host.com/bin/statistics >dev/null 2>&1)
Both
curl
and
wget
can perform
http
authentication, and can log in if you are using Apache login. See the platform documentation for
wget
or
curl
for more information. If using Template login, authentication will not be possible, and the CGI request will run as the WikiGuest user. If you use this workaround, the WebStatistics topics you are updating will have to be writable by WikiGuest, and you cannot add
statistics
to the
{AuthScripts}
list
If you do not have
curl
or
wget
available on your platform, Foswiki provides a very simple script that can post to or get from a web server. It has no authentication capabilities.
Deprecated! This script is deprecated and may be removed in a future release.
Run the utility
tools/geturl.pl
in your cron job and specify the URL of the
bin/statistics
script as a parameter as shown here:
0 0 * * * (cd /path/to/tools; ./geturl.pl POST mydomain.com /urlpath/to/bin/statistics?webs=Sandbox\;subwebs=1 >/dev/null 2>&1)
.
When running from the command line or a cron job, you can pass parameters to the script like this:
./statistics -logdate 200605 -webs Userweb,Sandbox -autocreate 1 -subwebs 1
Parameter |
Description |
Default |
autocreate |
Flag to request auto-creation of missing WebStatistics topics. 0=false 1=true |
(See logging and statistics page in bin/configure .) |
logdate |
Generate statistics for the specified year/month, spacified as YYYYMM |
current month |
subwebs |
Flag to request processing of subwebs of the requested webs. 0=false 1=true |
0 (Subwebs are not processed) |
webs |
comma-separated list of webs. |
all accessible webs |
Creating the WebStatistics topics
As of release 1.1.4 of Foswiki, the WebStatistics topics are no longer shipped by default. The
bin/statistics
script can automatically create the required topics when enabled in the configuration, or when requested by URL Parameter
autocreate=1
.
- If you want the Statistics topic to be automatically created whenever needed, in every web
- If you want to manually add the WebStatistics topic to a subset of webs
- Visit http://silverdye.us/wiki/bin/configure
Logging and Statistics
tab, and set {Stats}{AutoCreateTopic}
to Permitted
- Use the below form to run
statistics
on one or more webs.
- or add
-autocreate 1
to the statistics script as shown above.
- If yow want to prohibit autocreate of WebStatistics topics
Generating statistics manually by URL
The
bin/statistics
script can also be executed as a CGI script, Use the form at the top of this topic to run statistics.
As of Foswiki 1.1.5, the statistics script must be run using the "post" method. Direct entry of a URL is no longer allowed.
Tailoring the WebStatistics layout
The WebStatistics topics are not shipped with Foswiki by default. The topics are created on demand by the statistics script when requested by configuration. The topics are created as follows:
- The Main web is searched for WebStatisticsTemplate - if this topic does not exist
- If
{Stats}{AutoCreateTopic}
is enabled in the configuration, or the autocreate
parameter is passed to the statistics
script, then a new WebStatistics is created using the WebStatisticsTemplate topic found in the first step.
- If
autocreate
is not requested, and the WebStatistics topic does not exist, then statistics will not be computed for the web.
The template topic contains an
%INCLUDE%
for help text and table headings, and a critical
marker line
that defines the columns to be recorded by the statistics script. (This allows the help text or headings to be modified without needing to edit every WebStatistics topic.)
To tailor the help text or column heading, copy
DefaultWebStatistics to
DefaultWebStatistics and tailor as desired. This prevents your changes from being lost when Foswiki is updated.
To tailor the actual columns recorded and the order of the columns, copy
WebStatisticsTemplate to
WebStatisticsTemplate and tailor as desired. Then remove the previous WebStatistics and allow the statistics script to auto-create a new topic based upon the new template.
Alternatively you can edit the WebStatistics in each web.
Statistics are written into the WebStatistics in the following order.
- If a
marker line
is found in the topic, statistics are inserted into the topic after the marker line
.
- If no
marker line
is present, but the topic contains existing statistics, the current month is update, or a new month is written after the previous month.
- If no
marker line
is present and no previous statistics exist, a new line is added to the end of the topic.
Removal of the marker line causes statistics to be gathered in chronological order (oldest first). By default, statistics are reported in reverse chronological order.
The
marker line
defines the order of the columns collected by the
statistics
script. The order of the columns should correspond to the table heading in the
DefaultWebStatistics. Default marker line is:
| <!--statDate--> | <!--statViews--> | <!--statSaves--> | <!--statUploads--> | <!--statTopViews--> | <!--statTopContributors--> |
Restricting access to statistics topics
WebStatistics topics can have access controls like other topics.
If you want to have these access settings copied to new WebStatistics topics, follow these steps:
- Copy topic WebStatisticsTemplate from System web to Main web
- Edit the topic settings (via the "More" link) and write (if you want to restrict topics views to logged in users):
* Set DENYTOPICVIEW = WikiGuest
For existing WebStatistics topics you will need to write these settings manually.
Managing the WebStatistics topics
Each WebStatistics topic will continue to grow, a new row added every month. In addition, every update of the statistics topic will create a new entry in the WebStatistics topic revision history. These can become extremely large over time and Foswiki does not provide any mechanism for automatically archiving statistics topics. For good ongoing performance, it is recommended to archive statistics annually:
- Enable
{Stats}{AutoCreateTopic}
or add -autocreate 1
to the cron job that runs the statistics script.
- Rename the WebStatistics to
WebStatisticsYYYY
at year end.
- Optional: Tailor the DefaultWebStatistics topic, adding a search for archived statistics, for example:
%SEARCH{"." type="regex" topic="%STATISTICSTOPIC%*" excludetopic="%BASETOPIC%" scope="topic" nonoise="on" header="*Other Statistics Topics:*" format=" * $web.$topic"}%
Following these steps will start a fresh statistics topic with a clean revision history.