IRStats 2

From EPrints Documentation
Jump to: navigation, search


IRStats2 is a statistical framework for EPrints - It comes with some cool default tools and reports and it can also be customised to, for instance, add new metrics or data sets. It has a Javascript API to include stats on any pages you want.

IRStats2 is developed against EPrints 3.3 but it was written to also work on EPrints 3.2. Older versions of EPrints are, however, not supported.

Installation

Dependencies

The following perl libraries are required:

* Geo::IP or Geo::IP::PurePerl
* Date::Calc

Both can usually be installed via your Linux package managers (apt-get, yum, ...) or via CPAN if you are unable to locate a package.

e.g. in Debian/Ubuntu:

apt-get install libgeo-ip-perl libdate-calc-perl

EPrints 3.3

IRStats2 can be installed directly via the Bazaar on EPrints 3.3 which makes the installation much simpler than with EPrints 3.2.

EPrints 3.3.11 onwards

Install IRStats from the bazaar following installation of dependencies. Restarting apache afterwards is recommended.

EPrints 3.3.1 to 3.3.10

Following bazaar installation, two patches need to be applied if you would like to use the Google "map of the world" in your reports. Everything else should work as normal without the patches.

The patches relate to an incompatibility between the Prototype JS library (used by EPrints) and Google Charts (used by IRStats2). The two patches you need to apply are:

EPrints 3.2

You will have to manually copy the required files to your EPrints installation path. It is a low-risk operation since IRStats2 is a true add-on to EPrints and it does not interact with the core software.

Get the files from [1]GitHub or by following this link [tar.gz]. Copy the modules and various configuration files to your local archive (create the bin and cgi directories if they don't exist):

cp bin/* /opt/eprints3/archives/ARCHIVEID/bin/
cp cfg/* /opt/eprints3/archives/ARCHIVEID/cfg/
cp cgi/* /opt/eprints3/archives/ARCHIVEID/cgi/

It's a good idea to run a test at this point to see if anything has broken:

/opt/eprints3/bin/epadmin test

Add in the <head> sections of your template files (usually located in /opt/eprints3/archives/ARCHIVEID/cfg/lang/en/templates/) the following:

<script type="text/javascript" src="http://www.google.com/jsapi">// <!-- No script --></script>
<script type="text/javascript">
        google.load("visualization", "1", {packages:["corechart", "geochart"]});
</script>

Finally, restart the web server

Processing Stats

IRStats uses its own tables to manage statistics, which it populates from the EPrints access table (a table containing a row for every access to EPrints objects). Once installed, IRStats needs to process the full contents of this table. The following command needs to be run.

/opt/eprints3/archives/REPO_ID/bin/stats/process_stats REPO_ID --setup --verbose

Note that this may take a long time, perhaps up to several days for a large repository.

Following this initial run, the script needs to be added to the eprints crontab to run every night:

 perl /EPRINTS_ROOT/archives/REPOSITORYID/bin/stats/process_stats REPOSITORYID 1>/dev/null 2>/dev/null

...note the redirections of output to /dev/null will make the script run silently.

Viewing Stats

The main repository stats panel will be publicly available at: http://yourrepo.url/cgi/stats/report

Embedding Stats on Abstract Pages

Edit the EPrint Summary Page citation file (this can be done from the command line or the configuration editor) and add the following phrase near the bottom:

 <epc:phrase ref="lib/irstats2:embedded:summary_page:eprint:downloads"/>

Then restart apache and regenerate the abstract pages.

Troubleshooting

No style on stats

If you attempt to view the stats panel and it does not render correctly, run generate_static and restart apache.

Can't call method "add_trigger"

Error when running process_stats:

Use of uninitialized value in concatenation (.) or string at (eval 70) line 11.
Use of uninitialized value in concatenation (.) or string at (eval 70) line 16.
Use of uninitialized value in concatenation (.) or string at (eval 70) line 19.

------------------------------------------------------------------
---------------- EPrints System Error ----------------------------
------------------------------------------------------------------
Error in configuration:
Can't call method "add_trigger" on unblessed reference at /usr/share/eprints3/archives/sandbox/bin/../cfg/cfg.d/z_irstats2.pl line 162.


------------------------------------------------------------------
EPrints System Error inducing stack dump
 at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints.pm line 146.
	EPrints::abort("EPrints") called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints/Config.pm line 151
	EPrints::Config::load_system_config() called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints/Config.pm line 96
	EPrints::Config::init() called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints.pm line 706
	require EPrints.pm called at /usr/share/eprints3/archives/sandbox/bin/stats/process_stats line 12
	main::BEGIN() called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints.pm line 0
	eval {...} called at /usr/share/eprints3/archives/sandbox/bin/stats/../../../../perl_lib/EPrints.pm line 0

This is due to the FindBin library not working correctly. Open the process_stats script and remove the line:

use lib "$FindBin::Bin/../../../../perl_lib";

When executing, use -I to explicitly set the EPrints perl_lib directory:

perl -I/EPRINTS_ROOT/perl_lib /EPRINTS_ROOT/archives/ARCHIVEID/bin/stats/process_stats

Argument "/opt/eprints3/lib/geoip/GeoIP.dat" isn't numeric

If you see the error:

Argument "/opt/eprints3/lib/geoip/GeoIP.dat" isn't numeric in subroutine entry at /opt/eprints3/lib/plugins/EPrints/Plugin/Stats/Processor/Access/Country.pm line 36, <DATA> line 960.

This is due to a change in functionality of the GeoIP library. Open the file:

/EPRINTS_ROOT/lib/plugins/EPrints/Plugin/Stats/Processor/Access/Country.pm

...and replace the line:

$self->{geoip} = $pkg->new( $dat_file );

...with...

$self->{geoip} = $pkg->open( $dat_file );

Remember to add a suitable comment identifying who made the change, when it was made and why. This will make upgrading easier.

process_stats locked

If IRStats terminates prematurely, it can leave a lock in the database that will need to be removed. A script has been written to release this lock, but should only be run if you are certain that IRStats2 is not currently running. The code is available on github.

Technical Documentation

For more information, please see the IRStats 2 Technical Documentation page.