%META:TOPICINFO{author="TWikiContributor" date="1379282518" format="1.1" version="$Rev$"}%
---+!! !UsageStatisticsPlugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/UsageStatisticsPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/UsageStatisticsPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Statistics Reports

This plugins shows detailed usage statistics reports of TWiki content and users. Visit the following pages:

   * *[[UsageStatisticsOverview][Usage Statistics Overview]]* - overview statistics by month
   * *[[UsageStatisticsByUser][Usage Statistics by User]]* - statistics by user and month

%T% __Notes:__
   * Access to user statistice is restricted to administrators for privacy reasons.
   * Statistics are derived from the TWiki logs.

---++ Screenshots of Reports

%TABLE{ sort="off" }%
| *Usage Statistics Overview* | | *Usage Statistics by User* |
| [[%ATTACHURLPATH%/stats-overview-screen.png][<img src="%ATTACHURLPATH%/stats-overview-thumb.png" alt="stats-overview-thumb.png" width="300" height="233" />]] | | [[%ATTACHURLPATH%/stats-users-screen.png][<img src="%ATTACHURLPATH%/stats-users-thumb.png" alt="stats-users-thumb.png" width="235" height="233" />]] |
| click on image to enlarge | | click on image to enlarge |

---++ Syntax Rules

%T% You can safely ignore this section unless you want to build your own reports.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

The UsageStatisticsOverview and UsageStatisticsByUser pages embed the following variable to show usage statistics:

=%<nop>USAGESTATISTICS{ action="..." ... }%=

The =action= can be ="overview"=, ="user"= or ="monthlist"=.

__Supported parameters for =action="overview"= to generate overview statistics:__

| *Parameter* | *Description* | *Default* |
| =action="overview"= | Generate overview statistics | none |
| =month="2011-04"= | Month, format =YYYY-MM= | current month |

Statistics of the current month are shown by default. If a selected month has no statistics, this message is shown: "No statistics are available for this month."

__Supported parameters for =action="user"= to generate statistics by user:__

| *Parameter* | *Description* | *Default* |
| =action="user"= | Generate statistics by user | none |
| =user="..."= | %SYSTEMWEB%.WikiName of user | none |
| =month="2011-04"= | Month, format =YYYY-MM= | current month |

Statistics of the current month are shown by default. If no user is specified, this message is shown: "Please specify a user." If a selected month has no statistics, this message is shown: "No statistics are available for this month."

__Supported parameters for =action="monthlist"= to get list of months where statistics are available:__

| *Parameter* | *Description* | *Default* |
| =action="monthlist"= | Get list of months that have statistics logs | none |
| =reverse="on"= | Reverse the list, e.g. newest months first. | ="off"= |
| =format="..."= | Format for each month. =$month= expands to the month, format =YYYY-MM= | ="$month"= |
| =separator="..."= | Separator between months. | ="$n"= (newline) |

%ENDTWISTY%

---++ Plugin Installation &amp; Configuration

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==data/TWiki/UsageStatisticsOverview.txt== | Overview statistics topic |
        | ==data/TWiki/UsageStatisticsByUser.txt== | User statistics topic |
        | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/%TOPIC%/Core.pm== | Plugin Perl class |
        | ==pub/TWiki/Plugins/%TOPIC%/*.png== | Screenshots |
      * Set the ownership of the extracted directories and files to the webserver user.

   * Plugin __configuration and testing__:
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Test if the installation was successful: See UsageStatisticsOverview, UsageStatisticsByUser

%ENDTWISTY%

---++ Plugin Info

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Show detailed monthly usage statistics of TWiki content and users

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.PeterThoeny |
|  Copyright: | &copy; 2011 e-Ecosystems Inc <br /> &copy; 2011-2013 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Sponsor: | [[http://www.e-ecosystems.com/][e-Ecosystems, Inc]] |
|  Plugin Version: | 2013-09-15 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}% "
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2013-04-11: | TWikibug:Item7154: Minor doc fixes |
|  2013-04-11: | TWikibug:Item7154: Doc enhancements; document File::Temp dependency; add twisties |
|  2011-07-15: | TWikibug:Item6764: Minor fix to remove warning message in error log |
|  2011-07-10: | TWikibug:Item6725: Change global package variables from "use vars" to "our" |
|  2011-04-23: | TWikibug:Item6686: Initial version |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.2 (TWiki-4.3) |
|  CPAN Dependencies: | CPAN:File::Temp &gt; = 0.18 |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  [[TWiki:Plugins.Benchmark][Benchmarks]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/UsageStatisticsPlugin |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/UsageStatisticsPluginDev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/UsageStatisticsPluginAppraisal |

__Related Topics:__ UsageStatisticsOverview, UsageStatisticsByUser, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.UserDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory

%META:FILEATTACHMENT{name="stats-users-thumb.png" attachment="stats-users-thumb.png" attr="h" comment="" date="1303595119" path="stats-users-thumb.png" size="35593" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="stats-users-screen.png" attachment="stats-users-screen.png" attr="h" comment="" date="1303595119" path="stats-users-screen.png" size="112925" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="stats-overview-thumb.png" attachment="stats-overview-thumb.png" attr="h" comment="" date="1303595118" path="stats-overview-thumb.png" size="50389" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="stats-overview-screen.png" attachment="stats-overview-screen.png" attr="h" comment="" date="1303595117" path="stats-overview-screen.png" size="134515" user="TWikiContributor" version="1"}%
