{ "info": { "author": "Praekelt Foundation", "author_email": "dev@praekelt.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Framework :: Django", "Intended Audience :: Developers", "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Programming Language :: Python", "Topic :: Internet :: WWW/HTTP :: Dynamic Content" ], "description": "django-analytics\n================\n\nA basic Django app facilitating tracking of certain elementary metrics and statistics -\ngenerally just metrics which can be measured in terms of counts and cumulative counts.\n\nThis app could be useful for keeping track of registrations, page impressions, sessions,\nand so on. By default, it allows for tracking of registrations. Adding more metrics\nis a relatively straightforward task, as explained further on.\n\n.. contents::\n :depth: 5 \n\nQuick Installation\n------------------\n1. Save a copy of the ``django-analytics`` app in your Python path.\n2. Add it to your ``INSTALLED_APPS`` list in your Django project settings.\n3. Create a ``mod_analytics.py`` file for each of your apps that require some sort\n of tracking. See the `Creating a mod_analytics Script`_ section below.\n4. Run the following from the command line in order to install the various metrics\n and automatically make them active:\n\n::\n\n > python manage.py metrics --install\n\n5. Run the following from the command line to update the daily, weekly and monthly\n statistics for each of the active metrics:\n\n::\n\n > python manage.py metrics --calculate=ALL\n\nBy default, ``django-analytics`` comes with a ``registrations`` metric which counts\nthe number of users in the system based on their ``date_joined`` timestamp.\n\nCreating a mod_analytics Script\n-------------------------------\nIf, for example, you have an app called ``comments`` with the following ``models.py`` file:\n\n::\n\n from django.db import models\n from django.contrib.auth.models import User\n\n class Comment(models.Model):\n user = models.ForeignKey(User, related_name='comments')\n timestamp = models.DateTimeField(auto_now_add=True)\n comment = models.CharField(max_length=300)\n\nand you would like to track the total number of comments, you could\ncreate a ``mod_analytics.py`` script (in the same directory as your app's models)\nlooking like the following:\n\n::\n\n from analytics.basemetric import BaseMetric\n from models import Comment\n\n class TotalComments(BaseMetric):\n uid = \"totalcomments\"\n title = \"Total comments\"\n\n def calculate(self, start_datetime, end_datetime):\n return Comment.objects.filter(timestamp__gte=start_datetime,\n timestamp__lt=end_datetime).count()\n\n def get_earliest_timestamp(self):\n try:\n return Comment.objects.all().order_by('timestamp')[0].timestamp\n except IndexError:\n return None\n\n\nGeckoboard Integration and CSV Dumps\n------------------------------------\nIn order to allow for `Geckoboard `_ integration to allow for\nvisualisation of your statistics, as well as simple CSV dumping of statistics,\nin your project's ``urls.py``, add the following line:\n\n::\n\n urlpatterns = patterns('',\n # ...\n\n (r'^analytics/', include('analytics.urls')),\n\n # ...\n )\n\nNote that this project makes use of ``django-geckoboard`` (http://pypi.python.org/pypi/django-geckoboard),\nso all of the default ``django-geckoboard`` settings apply.\n\n**Geckboard Charts**\n\nThis will automatically add the following Geckoboard-related URLs to your project:\n\n``analytics/geckoboard/numbers``\n A `numbers widget `_.\n Supported GET variable parameters: ``uid``, ``daysback``, ``cumulative``, ``frequency``.\n ``daysback`` default: 7.\n``analytics/geckoboard/rag``\n A `RAG widget `_.\n Supported GET variable parameters: ``uids``, ``daysback``, ``cumulative``, ``frequency``.\n``analytics/geckoboard/pie``\n A `pie chart widget `_.\n Supported GET variable parameters: ``uids``, ``daysback``, ``cumulative``, ``frequency``.\n``analytics/geckoboard/line``\n A `line chart widget `_.\n Note that this can only plot a single metric per chart.\n Supported GET variable parameters: ``uid``, ``daysback``, ``cumulative``, ``frequency``.\n ``daysback`` default: 7.\n``analytics/geckoboard/geckometer``\n A `geck-o-meter widget `_.\n Supported GET variable parameters: ``uid``, ``frequency``, ``cumulative``, ``min``, ``max``.\n``analytics/geckoboard/funnel``\n A `funnel chart widget `_.\n Supported GET variable parameters: ``uids``, ``frequency``, ``cumulative``, ``type``,\n ``percentage``, ``sort``.\n\n**Geckoboard GET Variable Parameters**\n\n+----------------+--------------------------------------------------------------------------+\n| ``uid`` | The UID of the metric to display, if a single metric is to be displayed. |\n+----------------+--------------------------------------------------------------------------+\n| ``uids`` | The UIDs of the metrics to display, if multiple metrics are to be |\n| | displayed. |\n+----------------+--------------------------------------------------------------------------+\n| ``daysback`` | The numbers Geckoboard widget shows a single count, and the percentage |\n| | change from a previous count. This view returns the most recent count |\n| | or cumulative count, as well as the count or cumulative count from |\n| | ``days_back`` days ago. |\n+----------------+--------------------------------------------------------------------------+\n| ``cumulative`` | A boolean value (either ``t`` or ``f``) indicating whether the period |\n| | count is to be returned, or the cumulative count. Default: ``t``. |\n+----------------+--------------------------------------------------------------------------+\n| ``frequency`` | The frequency of the statistics to be returned. Can be ``d``, ``w`` or |\n| | ``m`` for daily, weekly or monthly, respectively. Default: ``d``. |\n+----------------+--------------------------------------------------------------------------+\n| ``min`` | The minimum value of a particular metric - usually for pie charts. |\n| | Default: 0. |\n+----------------+--------------------------------------------------------------------------+\n| ``max`` | The maximum value of a particular metric - usually for pie charts. |\n| | Default: 100. |\n+----------------+--------------------------------------------------------------------------+\n| ``type`` | Chart type - only applicable to the funnel chart. See the Geckoboard |\n| | API for more details. Default: ``standard``. |\n+----------------+--------------------------------------------------------------------------+\n| ``percentage`` | Whether or not to show a percentage - only applicable to the funnel |\n| | chart. See the Geckoboard API for more details. Default: ``show``. |\n+----------------+--------------------------------------------------------------------------+\n| ``sort`` | A boolean value (either ``t`` or ``f``) indicating whether or not to |\n| | sort the statistics - only applicable to the funnel chart. See the |\n| | Geckoboard API for more details. Default: ``f``. |\n+----------------+--------------------------------------------------------------------------+\n\n**CSV Dump**\n\nIt will also add the following CSV-related URLs to your project:\n\n``analytics/csv/``\n A simple view requiring the UID of the metric as its parameter, returning\n a CSV dump of all of the statistics for the given metric. By default, this returns\n the **daily** statistics for the metric.\n\n**CSV Dump GET Variable Parameters**\n\n+----------------+--------------------------------------------------------------------------+\n| ``frequency`` | The frequency of the statistics to be returned. Can be ``d``, ``w`` or |\n| | ``m`` for daily, weekly or monthly, respectively. Default: ``d``. |\n| | For example, ``analytics/csv/registrations?frequency=w`` will return all |\n| | of the weekly registrations over all time as a CSV dump. |\n+----------------+--------------------------------------------------------------------------+\n\n\nMetrics Explained\n-----------------\nThe ``django-analytics`` module creates ``Metric`` objects for each type of metric that\nneeds to be tracked, such as registrations, page impressions, etc. Each metric needs to\nhave a globally unique identifier (**UID**) so that it can be referenced from the command line\nby name, and a title to provide a little more of a description of what that metric\nis.\n\nEach metric has a number of ``Statistic`` objects associated with it, each ``Statistic``\nonly being a simple combination of date/time, a count for that date/time, a cumulative\ncount, and frequency.\n\nThe frequency can currently only be **daily**, **weekly** or\n**monthly**, and by default, each metric's statistics are calculated for all of those\nfrequencies (so a single metric can have multiple frequencies' statistics).\n\nIn general, the cumulative count is automatically calculated for you, and is simply the\nprevious day's/week's/month's cumulative count, added to the current day's/week's/month's\ncount.\n\nCommand Line Reference\n----------------------\nThe following options are available from the command line for the ``metrics`` management\ncommand:\n\n-l, --list Lists all of the available metrics, along with some basic information about each.\n-i, --install Scans the project for available metrics and creates or updates them where necessary.\n-a, --activate Activates the metric with the specified UID, e.g. ``--activate=registrations``.\n If you want to activate all metrics,\n simply specify ``--activate=ALL`` on the command line. Only active metrics will\n be included in a ``--calculate=ALL`` execution.\n-d, --deactivate Deactivates the metric with the specified UID. Again, you can specify\n ``--deactivate=ALL`` to deactivate all metrics.\n-c, --calculate Calculates the specified metric, e.g. ``--calculate=registrations``. Can\n specify ``--calculate=ALL`` to calculate all active metrics.\n-f, --frequency If the ``--calculate`` command is specified, this will allow one to force a particular\n frequency's statistics to be calculated. Possible values are: ``d`` (daily), ``w`` (weekly),\n ``m`` (monthly) and ``a`` (all). Default is *all*.\n--reset Deletes all of the ``Statistic`` objects associated with the specified metric.\n Can specify ``--reset=ALL`` to delete all statistics for all metrics, regardless\n of whether they are active or not.\n--drop-metric Deletes the actual ``Metric`` with the specified UID. Use ``--drop-metric=ALL``\n to drop all metrics (and their statistics) from the database.\n\nInner Workings\n--------------\nWhen running the ``manage.py metrics --install`` command, the following happens:\n\n1. The script searches through all the installed apps for your project and\n attempts to first find a ``mod_analytics`` module which it can import.\n2. It then searches through all of the classes in each ``mod_analytics`` module\n it encounters, and then attempts to find classes derived from the\n ``analytics.basemetric.BaseMetric`` class (an abstract class).\n3. For each valid class found which derives from the ``BaseMetric`` class, the script\n makes sure it has two functions: ``calculate``, and ``get_earliest_timestamp``.\n It also makes sure the class has two properties: ``uid`` and ``title``.\n4. If the class has these two functions, the script creates a ``Metric`` instance\n whose unique identifier and title are set to the ``uid`` and ``title`` values\n of the discovered class.\n\nThe ``calculate`` function takes two parameters: ``start_datetime`` and ``end_datetime``,\nand must simply return a count of the relevant metric between those two given dates. You can\nperform any calculations you need in this function to get to this final count value.\n\nTo understand the reasoning here, the ``analytics`` app has three broad calculation time periods\nwhich it attempts to calculate: **daily**, **weekly** and **monthly**. For a daily calculation,\nfor example, the ``start_datetime`` parameter supplied will resemble something like\n``datetime(2011, 5, 1)`` and the ``end_datetime`` parameter will resemble something like\n``datetime(2011, 5, 2)``. The ``calculate`` function must then return a count of the relevant\nmetric for the time period starting at 2011/05/01 00:00 and ending at 2011/05/02 00:00.\n**NOTE**: You should always return counts starting at exactly the given ``start_datetime``\nvalue (i.e. greater-than-equal-to), but *just before* the ``end_datetime`` value (i.e.\nless-than).\n\nThe ``get_earliest_timestamp`` function must simply return a ``datetime.datetime`` object\nindicating the earliest data's associated date/time, so that the analytics calculation routine\nknows the date at which to start calculating. If there are no entries yet, this function must\nreturn ``None``.\n\nAbstract Metrics\n----------------\n\nIf you want to create abstract metrics, simply create a separate Python file somewhere\nwhich will contain your \"abstract\" metrics. For example, create an ``abstract_metrics.py``\nfile which looks as follows:\n\n::\n\n from analytics import BaseMetric\n from django.contrib.auth.models import User\n\n class UserBaseMetric(BaseMetric):\n def calculate(self, start_datetime, end_datetime):\n return User.objects.filter(date_joined__gte=start_datetime,\n date_joined__lt=end_datetime).count()\n\n def get_earliest_timestamp(self):\n try:\n return User.objects.all().order_by('date_joined')[0].date_joined\n except IndexError:\n return None\n \nThen, in your ``mod_analytics.py`` file, just import your ``abstract_metrics`` module.\n**Note**: Do not import the ``UserBaseMetric``, just import the ``abstract_metrics`` module,\nas follows:\n\n::\n\n from analytics import BaseMetric\n import myapp.abstract_metrics\n\n class UserMetric(abstract_metrics.UserBaseMetric):\n uid = \"users\"\n title = \"Users\"\n\n\nTodo\n----\nThe following features are planned for future versions of ``django-analytics``:\n\n1. Custom visualisation integrated into Django admin back-end.\n2. Hourly statistics.\n3. More complex statistics, such as frequency plots/histograms.\n\nVersion History\n---------------\n\n+---------+------------------------------------------+\n| Version | Description |\n+=========+==========================================+\n| 0.0.1 | First version |\n+---------+------------------------------------------+", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/praekelt/django-analytics", "keywords": null, "license": "BSD", "maintainer": null, "maintainer_email": null, "name": "django-analytics", "package_url": "https://pypi.org/project/django-analytics/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/django-analytics/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/praekelt/django-analytics" }, "release_url": "https://pypi.org/project/django-analytics/0.0.1/", "requires_dist": null, "requires_python": null, "summary": "Django app facilitating tracking of arbitrary simple metrics.", "version": "0.0.1" }, "last_serial": 789087, "releases": { "0.0.1": [ { "comment_text": "", "digests": { "md5": "8c750edb86b0a7bf5d87cf1ebd3bf91d", "sha256": "62e08ecab07d33c4fbc15d69a588f7d525dfce743283b1e61ddf8b514842f6af" }, "downloads": -1, "filename": "django_analytics-0.0.1-py2.7.egg", "has_sig": false, "md5_digest": "8c750edb86b0a7bf5d87cf1ebd3bf91d", "packagetype": "bdist_egg", "python_version": "2.7", "requires_python": null, "size": 34622, "upload_time": "2011-07-25T14:26:22", "url": "https://files.pythonhosted.org/packages/4b/40/a2d745752639d140c04a9526526ca5f63e062be9690f0c310c94d992a456/django_analytics-0.0.1-py2.7.egg" }, { "comment_text": "", "digests": { "md5": "8f4654b7add1f480e34b164ac15afa25", "sha256": "e2aa62c0a8671dc8559d11d56cd526f97b5566fbe41b4f1327adae947d8412e6" }, "downloads": -1, "filename": "django-analytics-0.0.1.tar.gz", "has_sig": false, "md5_digest": "8f4654b7add1f480e34b164ac15afa25", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15475, "upload_time": "2011-07-25T14:26:17", "url": "https://files.pythonhosted.org/packages/13/20/5514586a8dbecc3eeb08b99132c293fabb034a954c3048817befe7adc753/django-analytics-0.0.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "8c750edb86b0a7bf5d87cf1ebd3bf91d", "sha256": "62e08ecab07d33c4fbc15d69a588f7d525dfce743283b1e61ddf8b514842f6af" }, "downloads": -1, "filename": "django_analytics-0.0.1-py2.7.egg", "has_sig": false, "md5_digest": "8c750edb86b0a7bf5d87cf1ebd3bf91d", "packagetype": "bdist_egg", "python_version": "2.7", "requires_python": null, "size": 34622, "upload_time": "2011-07-25T14:26:22", "url": "https://files.pythonhosted.org/packages/4b/40/a2d745752639d140c04a9526526ca5f63e062be9690f0c310c94d992a456/django_analytics-0.0.1-py2.7.egg" }, { "comment_text": "", "digests": { "md5": "8f4654b7add1f480e34b164ac15afa25", "sha256": "e2aa62c0a8671dc8559d11d56cd526f97b5566fbe41b4f1327adae947d8412e6" }, "downloads": -1, "filename": "django-analytics-0.0.1.tar.gz", "has_sig": false, "md5_digest": "8f4654b7add1f480e34b164ac15afa25", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 15475, "upload_time": "2011-07-25T14:26:17", "url": "https://files.pythonhosted.org/packages/13/20/5514586a8dbecc3eeb08b99132c293fabb034a954c3048817befe7adc753/django-analytics-0.0.1.tar.gz" } ] }