Table of Contents
QuickStats Plugin
Compatible with DokuWiki
- 2024-02-06 "Kaos" unknown
- 2023-04-04 "Jack Jackrum" unknown
- 2022-07-31 "Igor" unknown
- 2020-07-29 "Hogfather" yes
Similar to statistics
Installation
Search and install the plugin using the Extension Manager. 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:
- it records web stats
- it provides syntax for display of the stats on a standard dokuwiki page.
- 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. For efficency, it should be deleted once the month/year
is passed.
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~~
~~QUICKSTATS:total~~
~~QUICKSTATS:total~~ will print the total number of page hits since the start of record keeping.
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
Total page accesses from beginning of record keeping to present:
~~QUICKSTATS:total~~
The above can be configured for output by using this class: quick-total
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)
Sample Output of Basics
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:
- 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. - Date
The date of a query is confined to the year selected in the Year box. However, you can select multiple months. - 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:
- rename data/meta/quickstats/uniq_ip.ser to a new name and then re-run the admin panel.
- 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 either php_browscap.ini (19,597 KB), lite_php_browscap.ini (521 KB), or full_php_browscap.ini (96,969 KB). Whichever of these you use must be installed as php_browscap.ini
in the db
directory. The lite version comes pre-installed. The full version may cause the script to exhaust your allotted php script time and fail. You can update your version of browscap.ini as required, and it probably should be periodically checked. Check at http://browscap.org/ for updates 1).
Whichever version of
browscap
you use, you must rename it php_browscap.ini
Sorting Tables
- from Stuart Langridge: http://www.kryogenix.org/code/browser/sorttable/
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 GeoLite2-City. These services identify city and couuntry based upon the IP of the current visitor to the wiki. For this quickstats uses either MaxMind or geoPlugin. Maxmind is the default service. It can be by-passed using Configuration Option 15, which will then result in geoPlugin as your geo-Locating service. See below Configuration Settings.
Maxmind
For Maxmind, GeoLite2-City.mmdb must be installed on your server. You can install it automatically by going to the Admin panel. Click on Download DB
and the database should install. You should periodically reinstall GeoLite2-City.mmdb if you wish to keep current.
If you have any problems using the auto install feature you can go to the Maxmind database page. Follow the instructions for setting up an account and downloading the GeoLite 2 City database file. The download is is a .tar.gz
file with a name that uses this format: GeoLite2-City_20191105.tar.gz, where the number is the date the database was updated. Unpack this file and copy GeoLite2-City.mmdb to: quickstats/GEOIP/vendor/GeoLite2-City
.
Because of recent changes at Maxmind, you will now have to register for an account to download this database. This doesn't apply to the auto download.
GeoLite-City/GeoLite2-City
Maxmind changed the format of its databases. Previously, it consisted of two self-sufficent database files, GeoIPv6.dat and GeoLiteCity.dat. The upgrade, GeoLite2, handles both IPv4 and IPv6. GeoLite2 requires as a phar package. This package comes pre-installed with quickstats. If ever there is a need to reinstall, see the file GEOIP/initialize_vendor.txt.
The code for accessing the old GeoLite formats has been left in place. This means that if you have been using quickstats up until now and you disable both geoPlugin and GeoLite2, the plugin will continue to access the old databases. If for any reason you should still need the old databases, you can get them from this url: https://github.com/turnermm/utils/archive/geocity_zip.zip. This package contains both GeoIPv6.dat and GeoLiteCity.dat, which go into the GEOIP folder or the folder selected in the Configuration Settings2).
Geoplugin
geoPlugin is supplied by http://geoplugin.com. It is included with the quickstats plugin. geoPlugin is a free web-based service, while Maxmind's GeoLite2-City.mmdb
installs on your server. Quickstats defaults to geoPlugin, which means that quickstats is immediately ready to use upon installation. geoPlugin itself uses the MaxMind 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. 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.
Configuration Settings
- excludes: excludes listed IP addresses from stats, for instance if you don't want your own accesses to your site counted in the stats
- aborts: prevents listed IPs from accessing the site (for nuisance and spam accesses).
- geoip_local: if checked off Maxmind GeoLiteCity.dat must be installed in: lib/plugins/quickstats/GEOIP
- 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/)
- 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
- 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.
- 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.
- 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. - 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.
- 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
. - 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.
- 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.
- ajax: Delay final processing until after pages are loaded. This should result in smoother, faster page loading for some pages and templates. Defaults to
true
. - xcl_pages: Comma separated list of pages and/or namespaces to be excluded from statistics. For pages use the format
ns:pagename
. For namespaces use the formatns::
. In both cases give the complete namespace path: ns1:ns2:, etc. Initial namespace ids and root page names do not have an initial colon. Usens::
and not:ns::
. Similarly,pagename
, and not:pagename
. - by_pass_mmdb: By-pass GeoLite2-City. In this case the web-based geoplugin will be the default geo-positioning tool.
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 or github for questions and issues. Thanks.
Development
Recent Changes
- fixed access to missing key 'test' in class qs_geoliteCity::__construct (2023-02-28 19:45)
- Merge branch 'master' of github.com:turnermm/quickstats (2022-02-13 18:37)
- Merge pull request #35 from mprins/patch-1 (2022-02-13 18:31)
- sync date with listed date on url so the plugin manager can work prop… (2022-02-03 23:53)
- Updates version (2022-01-07 17:07)
- Merge pull request #34 from turnermm/tmp (2022-01-07 17:01)
- fixed bracket error in syntax.php (2022-01-07 16:51)
- Fix null array error in uasort in syntax.php (2022-01-07 16:43)
- in syntax.php (l.345) checks if GeoLiteCity.dat exists before accessi… (2020-07-24 15:06)
- Adds total option to QUICKSTATS and adds a new GEOIP/GeoLiteCity.dat … (2020-07-23 18:36)
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.