ckanext-statistics

A CKAN extension for accessing instance statistics.

Overview

Shows statistics for datasets and downloads on the CKAN instance.

NB: This extension currently only works for the Natural History Museum, London, due to embedded data.

Installation

Path variables used below:

• $INSTALL_FOLDER (i.e. where CKAN is installed), e.g. /usr/lib/ckan/default
• $CONFIG_FILE, e.g. /etc/ckan/default/development.ini

Installing from PyPI

pip install ckanext-statistics

Installing from source

1. Clone the repository into the src folder:

   cd $INSTALL_FOLDER/src
   git clone https://github.com/NaturalHistoryMuseum/ckanext-statistics.git
   

2. Activate the virtual env:

   . $INSTALL_FOLDER/bin/activate
   

3. Install via pip:

   pip install $INSTALL_FOLDER/src/ckanext-statistics
   

Installing in editable mode

Installing from a pyproject.toml in editable mode (i.e. pip install -e) requires setuptools>=64; however, CKAN 2.9 requires setuptools==44.1.0. See our CKAN fork for a version of v2.9 that uses an updated setuptools if this functionality is something you need.

Post-install setup

1. Add 'statistics' to the list of plugins in your $CONFIG_FILE:

   ckan.plugins = ... statistics
   

2. Upgrade the database to create the tables:

   ckan -c $CONFIG_FILE db upgrade -p statistics
   

Configuration

These are the options that can be specified in your .ini config file.

Cache settings

This extension uses two named Beaker cache regions: statistics_short (intended for relatively short-term caching, e.g. 1 day) and statistics_long (intended for more persistent, long-term caching, e.g. 1 week). Neither of these have any default settings configured, and they can either be configured together or separately.

To define a setting for both caches:

To define settings separately:

Please see Beaker's configuration docs for more information and additional options.

Usage

Actions

download_statistics

Statistics for downloads of datasets from the instance.

from ckan.plugins import toolkit

# all of these filters are optional
data_dict = {'resource_id': RESOURCE_ID, 'year': YEAR, 'month': MONTH}

toolkit.get_action('download_statistics')(context, data_dict)

dataset_statistics

Statistics for dataset records.

from ckan.plugins import toolkit

# these filters are optional
data_dict = {
    'resource_id': RESOURCE_ID,
}

toolkit.get_action('dataset_statistics')(context, data_dict)

Testing

There is a Docker compose configuration available in this repository to make it easier to run tests. The ckan image uses the Dockerfile in the docker/ folder.

To run the tests against ckan 2.9.x on Python3:

1. Build the required images:

   docker compose build
   

2. Then run the tests. The root of the repository is mounted into the ckan container as a volume by the Docker compose configuration, so you should only need to rebuild the ckan image if you change the extension's dependencies.

   docker compose run ckan