DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:quickstats

QuickStats Plugin

Compatible with DokuWiki

  • 2016-06-26 "Elenor Of Tsort" yes
  • 2015-08-10 "Detritus" yes
  • 2014-09-29 "Hrun" yes
  • 2014-05-05 "Ponder Stibbons" yes

plugin A statistics generator for web traffic on DokuWiki sites

Last updated on
2016-07-31
Provides
Syntax, Action
Repository
Source

Similar to statistics

Tagged with statistics

Installation

Install the plugin using the Plugin Manager and the download URL above, which points to latest version of the plugin. Refer to Plugins on how to install plugins manually.

For a sample of output for December 2011, see fckgLite stats.

Description

This plugin keeps track of page, geo-location, browser, operating system, and IP accesses. It tracks only data attached to Dokuwiki namespace:page IDs. It will not keep track of media files that are downloaded from your site or include in its counts images that are displayed on your pages; nor will it include pages that are 'included' using the include plugin or discussion boxes inserted into your pages using the discussion plugin. Its data is based solely on the initial URL that fetches pages into the browser.

Quickstats is set up to work right out of the box in its initial installation. It does not use a database back-end and because of this may not be suitable for high-volume sites.

It comes with an administration panel capable of detailed queries.

Examples/Usage

quickstats has three functions:

  1. it records web stats
  2. it provides syntax for display of the stats on a standard dokuwiki page.
  3. it provides a query interface in the quickstats admin panel for making specific and detailed queries.

The statistics are saved on a month-to-month basis and so, when accessed for display, are accessed for a specified month/year. They are saved automatically, from the moment the plugin is installed. In the admin panel, queries can be made for multiple months within any single year.

Syntax

~~NOCACHE~~

~~QUICKSTATS:<month_year>&<category><;;depth>~~

The depth parameter limits the number of rows of output to depth number. The ~~NOCACHE~~ macro insures that your page output is always current.

Stats for current month

~~QUICKSTATS:~~  
~~QUICKSTATS:basics<;;depth>~~  
~~QUICKSTATS:ip<;;depth>~~
~~QUICKSTATS:misc<;;depth>~~
~~QUICKSTATS:countries<;;depth>~~
~~QUICKSTATS:pages<;;depth>~~
~~QUICKSTATS:ua<;;depth>~~

Stats for a previous month

~~QUICKSTATS:<month_year><;;depth>~~
~~QUICKSTATS:<month_year>&basics<;;depth>~~
~~QUICKSTATS:<month_year>&ip<;;depth>~~
~~QUICKSTATS:<month_year>&misc<;;depth>~~
~~QUICKSTATS:<month_year>&countries<;;depth>~~
~~QUICKSTATS:<month_year>&pages<;;depth>~~
~~QUICKSTATS:<month_year>&ua<;;depth>~~

Months are numbered from 1 to 12:

  • 1_2012 = January 2012
  • 12_2011 = December 2011

~~QUICKSTATS:~~ is a synonym for ~~QUICKSTATS:basics~~

~~QUICKSTATS:<month_year>~~ is a synonym for ~~QUICKSTATS:<month_year>&basics~~

Example 1

   ~~QUICKSTATS:1_2011~~

This outputs 'basics' for January 2011.

Example 2

     ~~QUICKSTATS:12_2011&pages;;10~~

The above outputs the top 10 pages for December 2011. The format would be as follows:

Page Accesses
1  	other:items	   372
2  	blog:start	    12
3  	start	            12
4  	other:features	    11
5  	other:stuff	     7  
.   .   .    .    .   .    .
.   .   .    .    .   .    .
10      least_accessed       1 

Number of pages accessed: 10
Total accesses: 420

Columns are: Rank in order of most accesses, page name, number of accesses.

Example 3

If depth is set to -1, then only the final totals will be output. For instance:

  ~~QUICKSTATS:pages;;-1~~

This outputs only the page totals for the current year, without the list of pages:

     Number of pages accessed: 10
     Total accesses: 420

Output for diffferent parameters

basics:

  • Operating systems
  • Browsers
  • Countries
  • Pages

misc:

  • Operating systems
  • Browsers

countries:

  • Countries
  • table consisting of Countries from which page accesses occur and the number of accesses

ip:

  • IP addresses
  • table consisting of IP addresses and number of accesses from that address
  • running mouse over the IP address shows the country of origin and the last User Agent

Because of the large number of ip's that can access a site, the ip table is set to a max-height of 400px with overflow:auto. These settings will create scrolling for larger tables and can of course be changed.

ua:

  • User agent (Defaults to the browser)
  • table consisting of IP, Country of Origin, User Agent(s), and number of Accesses by IP;
    some IP's access the web by multiple browsers and/or user agents
  • second table consisting of user agents and total number of accesses by each user agent

pages:

  • Pages (namespace:page)
  • table consisting of namespace:page and number of accesses
  • running the mouse cursor over the page name shows the date of the last access of the page
  • clicking on the link opens a pop-up with the referenced page (pop-ups may need to be enabled)

Automating syntax plugin with Dokuwiki templates

If you create a directory using a namespace template, you can automate the creation of Quickstats documents. For instance:

_template.txt
~~NOCACHE~~
 
~~QUICKSTATS:@FILE@&basics~~
 
~~QUICKSTATS:@FILE@&ip~~

To use this template you open a new file with the <month>_<year> parameters. For instance, opening a page named 7_2012, will create the following syntax:

    ~~NOCACHE~~

    ~~QUICKSTATS:7_2012&basics~~

    ~~QUICKSTATS:7_2012&ip~~

Admin Panel

Query Facility

The administration panel has facilities for making specific, detailed queries against the quickstats data files. Some of the information available here is not available through the syntax plugin's output. In particular, it will give extended data on countries, Dokuwiki search queries, and parameters embedded in query strings which access your pages. Using this panel, you can query information about specific countries, User Agents, IP addresses and Dokuwiki pages for individual months and groups of months.

The Query Form

This is a partial view of the query form:

  1. Quickstats Pages
    a menu listing of Quickstats pages created with the Quickstats syntax facility. You can click on any of these menu items and the stats page will open in a new window. By following the instructions on creating pages, you can always have specific up-to-date data — up-to-date because the pages will always renew their data, as long as the ~~NOCACHE~~ directive is included on the page.
  2. Date
    The date of a query is confined to the year selected in the Year box. However, you can select multiple months.
  3. The Unique IPs and Page Accesses show the cumulative totals since the start of record-keeping on the site and the totals for the current month. The cumulative totals assume that you are accessing the admin panel at least once every month. If you do not, then the unaccessed months will not show up in the cumulative totals. In such cases, you can do one of two things:
    1. rename data/meta/quickstats/uniq_ip.ser to a new name and then re-run the admin panel.
    2. set to true the rebuild_uip option (see configuration_settings below);

There are complete instructions in the Admin Panel as to how use the Query facility.

Cache Maintenance

As explained under Sorting Tables, quickstats keeps a list of pages which use the quickstats syntax module. The admin panel enables you to keep this list up-to-date.

Modules

Browser Info

For browser information, quickstats uses browscap.ini from Gary Keith and the get_browser_local() function developed by Alexandre Alapetite for searching browscap.ini. These are included with the quickstats plugin. You can update your version of browsercap.ini as required. If you opt for the Full version, rename it php_browsercap.ini.

  • from Gary Keith and others
    The browsercap project is in transition, and the old URLs are no longer active. The most recent versions of browsercap for php can be found here: http://browscap.org/. I have posted a copy of the latest version on my development site but it will be best to check at browscap.org.

Sorting Tables

The tables for pages, ips, and countries are sortable by clicking on the column headers. In order to minimize loading time, this script is accessed only when a page uses the quickstats syntax. Every time you create a quickstats page or make a change to the page, its id is cached (if not already in the cache file). When quickstats finds a page id in its cache, it loads the sorttable script. You can remove an id from the cache using the admin panel. You can also use the configuration manager to create a list of page names that require sorttable.js. This list is always checked first.

Geo-locating

For geo-locating quickstats uses either geoPlugin or Maxmind's GeoLiteCity. The geoPlugin and geoipcity.inc are included with the quickstats distribution. The GeoLiteCity.dat database has to be installed on your server as described below.

geoPlugin is a free web-based service, while Maxmind's GeoLiteCity.dat installs on your server. Quickstats defaults to geoPlugin, which means that quickstats is immediately ready to use upon installation. GeoLiteCitydat must be installed into a directory on your server. See Configuration Settings below for how to choose between these two services.

Benefits and Downsides

With GeoLiteCity, quickstats always has instant and secure access to the location data which it needs. However, it is recommended that you re-install updated copies every 6 weeks, in order to keep current with changing IP data. On Linux servers this is simple enough to do with a cron job; see sample script below.

geoPlugin, on the other hand, is always current and does not have to be installed on your server. Its data is retrieved via an http access. Responses from geoplugin.com tend to be fast, but there is always the question of delay and processing time, since you are accessing an off-site database.

Installing GeoLiteCity.dat

Using the Download Button in the Administration Panel

The simplest way to install GeoLiteCity.dat and GeoIPv6.dat is by means of the Download DB button in the administration panel. This will download and unpack the database files in the quickstats/GEOIP directory. To activate this installation you must set the geoip_local option to true in the Configuration Manager.

Manual Installation

To install GeoLiteCity.dat manually, it must be downloaded from Maxmind:

 http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz

Unpack this file and place it in either in /usr/local/share/GeoIP(Linux default) or any other convenient directory. If it is not installed in /usr/local/share/GeoIP, then you must enter the complete path to the directory in the text box for the geoip_dir configuration option.1) If you use this method, you should make sure that 'geoip_local' is unchecked. See Configuration Settings.

Installing GeoIPv6.dat manually

The database supporting IPv6 must be installed manually in the same directory as GeoLiteCity.dat. It must be downloaded from maxmind at the following url:

 https://github.com/turnermm/quickstats/archive/ip_v6.zip

This must be downloaded and unzipped.

Sample Cron Script

maxmind.sh
#!/bin/sh
cd /usr/local/share/GeoIP/
SECS=`date "+%b_%d_%y"`
 
if [ -f GeoLiteCity.dat ]
then
BAK="GeoLiteCity.dat.$SECS"
mv GeoLiteCity.dat $BAK
fi
 
wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
gunzip GeoLiteCity.dat.gz
 
if [ -f GeoIPv6.dat ]
then
BAK="GeoIPv6.dat.$SECS"
mv GeoIPv6.dat $BAK
fi
 
wget http://geolite.maxmind.com/download/geoip/database/GeoIPv6.dat.gz
gunzip GeoIPv6.dat.gz

ipv6 Support

The current version of quickstats comes with ipv6 support. If for any reason this version should not behave as expected, you can revert to the original ipv4 version: ip_v4.zip

Configuration Settings

  1. excludes: excludes listed IP addresses from stats, for instance if you don't want your own accesses to your site counted in the stats
  2. aborts: prevents listed IPs from accessing the site (for nuisance and spam accesses).
  3. geoip_local: if checked off Maxmind GeoLiteCity.dat must be installed in: lib/plugins/quickstats/GEOIP
  4. geoip_dir: if geoip_local is not checked off quickstats will look in this directory for GeoLiteCity.dat (it defaults to /usr/local/share/GeoIP/)
  5. geoplugin: if this option is checked the geoPlugin will be used for IP geo-locating (defaults to true); with this set to true GeoLIteCity.dat is not needed
  6. long_names: sets maximum number of characters when outputting long names. Defaults to 30 and -1 sets length to unlimited. When a name is truncated, it will be highlighted and the full name will appear with a mouse over.
  7. show_dates: if set to true quickstats saves the latest timestamp for the page access and displays it in date format on a mouse over the page name. Turning off this feature might help reduce load.
  8. show_country: when set to true, quickstats displays the country of origin of IPs listed with the ip mode. This feature is not available when geoplugin is set to true, because it takes too much time to download the country information over http. By contrast GeoLiteCity.dat is immediately available on the server and involves no extra overhead when fetching data.
  9. sorttable_ns: comma separated list of whole or partial namespaces and page names which require sortable output; tables in pages and namespaces matching names in this list will always use the sorted table header mechanism.
  10. max_exec_time: Maximum seconds for which to run queries in quickstats admin panel. Defaults to 60. This cannot work if safemode is in effect; if safemode is set to on, then the only way to increase the execution time for PHP scripts is in php.ini by re-setting max_execution_time.
  11. rebuild_uip: In the admin panel, the cumulative total of unique IP addresses assumes that you access the admin panel at least once per month. If you miss a month or months, then set this to true and the unique IP cache will be rebuilt. (See above: admin_panel) But remember to set it back to false after you've rebuilt your cache, otherwise it will rebuild each time you access your admin panel.
  12. hide_sidebar: In templates which use Dokuwiki's sidebar configuration setting, enter the name of a namespace where quickstats pages are saved. When a page is opened in that namespace the sidebar will be hidden. This enables a wide display for quickstats tables, where they might otherwise be cut off at the right.

Formatting

Quickstats comes with two style sheets in the top level directory, style.css and style.wide.css. The latter is an effort to accommodate wide layouts, where the tables tend to overlap. To use the wide you must change its name from style.wide.css to style.css. Either of these can be edited to format output to your own specifications. The basics setting has hard-coded CSS for the three-column layout. But the width of the columns and the up/down left/right positioning can be adjusted using the CSS selectors which begin with basics_: for instance div.countries_basics, which applies to the countries output. The left margin of the IP div (div.quickstats.ip) is set to line up with the hard-coded basics settings and can be changed from within style.css, as can its width and top/bottom and left/right positioning.

The CSS for the categories when requested individually is left open for your own designing:

/* placeholders for individual css formatting */
div.quickstats.misc span.title, div.quickstats.page span.title, div.quickstats.countries span.title {}
div.quickstats.misc { }
div.quickstats.pages {}
div.quickstats.countries { }
div.quickstats.ua {}

span.title refers to the heading at the top of each output category. You can also change the CSS for the totals that appear at the bottoms as well as for the IP category, which in the default style.css are pre-styled. These are, respectively, div.quickstats span.total and div.quickstats.ip.

Discussion

Please use the forum for questions. Thanks.

Suggestions:

  1. The ability to request multiple months at once (with merged results) or even to request all data.
  2. Listing available months as links. Clicking on the links would show the data.
  3. Some way to view the current month.
  4. The query feature in the admin only requests very precise bits of data. Since this plugin is most interesting to admins, it would be nice if the admin UI let you get general statistics for any month, selected from a list of available months.

-Ziothzioth
Zioth

Could you post these issues to the forum or to the github issues tracker? If I understand your questions by the way, I think that most of the issues are already covered by the plugin. See, for instance, The Query Form above.
Thanks.

-Syrus

I've put my suggestions (and one more not listed here) in the github issue tracker. -Ziothzioth
Zioth

This plugin made my DokuWiki very slow.
Have you read the section on Geo-locating? And please use the forum.

Development

Recent Changes

For complete details on fixes and upgrades, see the quickstats commits panel on github.

Known Bugs and Issues

10-Dec-2011
Fixed bug in date recognition in Syntax.php, where only dates with double-digit months were being recognized, i.e.: 12_2011, but not 1_2012
2-Jan-2012
Fixed several PHP warnings in both admin.php and action.php caused by failures to load arrays, where no data was available.

Upgrades and Changes

12-Dec-2011
Loosened up the hard-coded CSS for the basics mode. See above.
14-Dec-2011
Added sorting to tables. See sorting_tables.
17-Dec-2011
Enabled row depth setting for user agent table and added accesses column
11 October 2014
Support for hiding sidebar
13 October 2014
Merged ipv6 branch into master

Following all apply to Admin Panel:
31-Dec-2011
1. Upgraded admin panel with facility for detailed, specific queries and results
2. Saves new data types, including Dokuwiki search terms and terms found in query strings
2-Jan-2012
1. Added status line with page and unique IP totals (with facility to do the unique IP calculations)
2. Added requires to conditionally load utf8 module for pre-Lemming distros
7-Jan-2012
Greatly expanded admin panel with capacity for complex queries
8-Jan-2012
1. Extended User Agent matching to brief page priority output
2. Added search facility to User Agent drop-down menu
9-Jan-2012
1. Added accumulated total accesses to bottoms of tables
2. Added header to output consisting of the Query spec that was used to fetch the response
5 Feb 2012
1. Added config option for maximum time out for queries run in the admin panel
8 May 2012
1. Page queries can now be made for multiple months
15 March 2014
Added support for downloading geoLiteCity.dat from administration panel.

1)
For additional installation instructions see http://www.maxmind.com/app/installation?city=1
plugin/quickstats.txt · Last modified: 2017-01-08 16:54 by turnermm