Django Silent Mammoth Whistle
#############################
A super-simple user analytics tool that tracks user behaviour based on web requests to your Django app.
It's intended for use with libraries such as `htmx <https://htmx.org>`_, which generally make a web request for each user interaction. It also includes a JavaScript function for tracking purely client-side actions (e.g. things you might use `Alpine.js <https://alpinejs.dev/>`_ for). The UI is designed for small projects where understanding individual user behaviour is useful.
Features
========
* (optional) Automatic tracking of all web requests - no additional code needed in your project
* JavaScript function for tracking client-side actions
* Separate reporting of authenticated and anonymous sessions
* Shows top platforms, top user-agents (using `user-agents <https://pypi.org/project/user-agents/>`_), top viewport sizes, and new users, for each month
* Detects and hides bot traffic
* Tracking cookies can be disabled (you just won't see viewport size data)
* All data is stored in a single table with no relations to your project's tables
Requirements
============
Django 4.2+ and Python 3.8+
Installation
============
1. ``pip install django-silent-mammoth-whistle``
2. Add to ``INSTALLED_APPS`` setting - ideally just above the main app::
INSTALLED_APPS = [
...,
"silent_mammoth_whistle",
...,
]
3. Add middleware. At the end is fine::
MIDDLEWARE = [
...,
'silent_mammoth_whistle.middleware.SilentMammothWhistleMiddleware',
]
4. Include the silent mammoth whistle URLconf in your project urls.py. The URL (e.g. ``/mammoth``) can be anything you like::
urlpatterns = [
...,
path('/mammoth', include('silent_mammoth_whistle.urls')),
...,
]
5. Add ``<script src="{% static 'silent_mammoth_whistle/js/whistle.js' %}"></script>`` to your templates
6. Run migrations ``./manage.py migrate silent_mammoth_whistle``
Configuration
=============
All configuration is optional. The default configuration will track request methods, paths (urls), and response status codes.
settings.py
-----------
``WHISTLE_USER_ID_FIELD``
Defaults to ``'id'``
The name of a ``User`` model attribute that is used as the unqiue user identifier. It is displayed in the UI and is used for determining which web requests belong to which users. Sessions are based on this id.
``WHISTLE_CLIENT_EVENT_PATH``
Defaults to ``'/whistle'``
The url used by the ``whistle`` function in ``whistle.js`` to make web requests using JavaScript.
This is used in 2 places: 1) in the middleware, and 2) in the whistle.js file. If you change this setting, you will need to set the same value in a global (window) var called ``whistleClientEventPath`` using JavaScript.
``WHISTLE_COOKIES``
Defaults to ``True``
When True, a cookie is added to clients and is used with some JavaScript to record viewport dimensions. I don't think this constitutes a "tracking cookie", but if you think it does and you don't want that, just set this to ``False``.
``WHISTLE_AUTOLOG_REQUEST_METHOD``
Defaults to ``True``
Automatically adds the request method (e.g. POST) to the whistle.
``WHISTLE_AUTOLOG_REQUEST_PATH``
Defaults to ``True``
Automatically adds the request path to the whistle.
``WHISTLE_AUTOLOG_RESPONSE_CODE``
Defaults to ``True``
Automatically adds the response status code to the whistle.
When this is True, a count of 4xx and 5xx response codes is also displayed next to each session on the main page, and 4xx and 5xx responses are given an orange/red color when viewing the whistle details for a session.
Usage
=====
By default, silent mammoth whistle will record all web requests (specifically the HTTP method, response code, and path/URL).
You can also record additional data for a request.
.. code-block:: python
request.whistle.request('put a string here')
You can record as much data as you like, and you can make as many of these ``request.whistle.request()`` calls as you like. Silent mammoth whistle is super-simple and all data is cast to strings using ``str()`` before saving. Silent mammoth whistle will merge the strings from all the calls into a single string, separated by a tab when rendered.
Practical example time! This line will record the fields present in a POST request. This could be useful if your form has many optional fields and you want to know which ones were included by the user.
.. code-block:: python
request.whistle.request('fields=' + ", ".join(request.POST.dict().keys()))
When viewing session details in silent mammoth whistle, you'll see 3 columns: time, request, and response. Request is the obvious column to use, but you might like to separate tracking of what the user requested from how the server responded. E.g.
.. code-block:: python
request.whistle.response('fields in error=' + ", ".join(form.errors.dict().keys()))
These calls all start with ``request.`` because silent mammoth whistle adds a ``whistle`` object to the standard Django ``request`` object.
JavaScript API
==============
The JavaScript API is similar to the above.
.. code-block:: javascript
whistle('Edit dialog box open')
``whistle`` takes an unlimited number of arguments. Each argument is added to the whistle.
Bot detection
=============
Bot traffic is recorded and then hidden when viewing whistles. This
Raw data
{
"_id": null,
"home_page": null,
"name": "django-silent-mammoth-whistle",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "django, analytics, user, tracking",
"author": null,
"author_email": "Ben Michie <benopotamus@tinku.net>",
"download_url": "https://files.pythonhosted.org/packages/a0/fc/76df1d2543a65e1f79f581c75742acf2e5b0d11f8820bbe62b825f265c95/django_silent_mammoth_whistle-2.2.tar.gz",
"platform": null,
"description": "Django Silent Mammoth Whistle\n#############################\n\nA super-simple user analytics tool that tracks user behaviour based on web requests to your Django app.\n\nIt's intended for use with libraries such as `htmx <https://htmx.org>`_, which generally make a web request for each user interaction. It also includes a JavaScript function for tracking purely client-side actions (e.g. things you might use `Alpine.js <https://alpinejs.dev/>`_ for). The UI is designed for small projects where understanding individual user behaviour is useful.\n\nFeatures\n========\n\n* (optional) Automatic tracking of all web requests - no additional code needed in your project\n* JavaScript function for tracking client-side actions\n* Separate reporting of authenticated and anonymous sessions\n* Shows top platforms, top user-agents (using `user-agents <https://pypi.org/project/user-agents/>`_), top viewport sizes, and new users, for each month\n* Detects and hides bot traffic\n* Tracking cookies can be disabled (you just won't see viewport size data)\n* All data is stored in a single table with no relations to your project's tables\n\nRequirements\n============\n\nDjango 4.2+ and Python 3.8+\n\nInstallation\n============\n\n1. ``pip install django-silent-mammoth-whistle``\n\n2. Add to ``INSTALLED_APPS`` setting - ideally just above the main app::\n\n\t\tINSTALLED_APPS = [\n\t\t\t...,\n\t\t\t\"silent_mammoth_whistle\",\n\t\t\t...,\n\t\t]\n\n3. Add middleware. At the end is fine::\n\t\n\t\tMIDDLEWARE = [\n\t\t\t...,\n\t\t\t'silent_mammoth_whistle.middleware.SilentMammothWhistleMiddleware',\n\t\t]\n\t\n4. Include the silent mammoth whistle URLconf in your project urls.py. The URL (e.g. ``/mammoth``) can be anything you like::\n\t\n\t\turlpatterns = [\n\t\t\t...,\n\t\t\tpath('/mammoth', include('silent_mammoth_whistle.urls')),\n\t\t\t...,\n\t\t]\n\t\n5. Add ``<script src=\"{% static 'silent_mammoth_whistle/js/whistle.js' %}\"></script>`` to your templates\n\n6. Run migrations ``./manage.py migrate silent_mammoth_whistle``\n\nConfiguration\n=============\n\nAll configuration is optional. The default configuration will track request methods, paths (urls), and response status codes.\n\nsettings.py\n-----------\n\n``WHISTLE_USER_ID_FIELD``\n\n\tDefaults to ``'id'``\n\n\tThe name of a ``User`` model attribute that is used as the unqiue user identifier. It is displayed in the UI and is used for determining which web requests belong to which users. Sessions are based on this id.\n\n``WHISTLE_CLIENT_EVENT_PATH``\n\n\tDefaults to ``'/whistle'``\n\n\tThe url used by the ``whistle`` function in ``whistle.js`` to make web requests using JavaScript.\n\n\tThis is used in 2 places: 1) in the middleware, and 2) in the whistle.js file. If you change this setting, you will need to set the same value in a global (window) var called ``whistleClientEventPath`` using JavaScript.\n\n``WHISTLE_COOKIES``\n\n\tDefaults to ``True``\n\n\tWhen True, a cookie is added to clients and is used with some JavaScript to record viewport dimensions. I don't think this constitutes a \"tracking cookie\", but if you think it does and you don't want that, just set this to ``False``.\n\n``WHISTLE_AUTOLOG_REQUEST_METHOD``\n\n\tDefaults to ``True``\n\n\tAutomatically adds the request method (e.g. POST) to the whistle. \n\n``WHISTLE_AUTOLOG_REQUEST_PATH``\n\n\tDefaults to ``True``\n\n\tAutomatically adds the request path to the whistle.\n\n``WHISTLE_AUTOLOG_RESPONSE_CODE``\n\n\tDefaults to ``True``\n\n\tAutomatically adds the response status code to the whistle. \n\t\n\tWhen this is True, a count of 4xx and 5xx response codes is also displayed next to each session on the main page, and 4xx and 5xx responses are given an orange/red color when viewing the whistle details for a session.\n\n\nUsage\n=====\n\nBy default, silent mammoth whistle will record all web requests (specifically the HTTP method, response code, and path/URL).\n\nYou can also record additional data for a request.\n\n.. code-block:: python\n\n\trequest.whistle.request('put a string here')\n\nYou can record as much data as you like, and you can make as many of these ``request.whistle.request()`` calls as you like. Silent mammoth whistle is super-simple and all data is cast to strings using ``str()`` before saving. Silent mammoth whistle will merge the strings from all the calls into a single string, separated by a tab when rendered.\n\nPractical example time! This line will record the fields present in a POST request. This could be useful if your form has many optional fields and you want to know which ones were included by the user.\n\n.. code-block:: python\n\n\trequest.whistle.request('fields=' + \", \".join(request.POST.dict().keys()))\n\nWhen viewing session details in silent mammoth whistle, you'll see 3 columns: time, request, and response. Request is the obvious column to use, but you might like to separate tracking of what the user requested from how the server responded. E.g.\n\n.. code-block:: python\n\n\trequest.whistle.response('fields in error=' + \", \".join(form.errors.dict().keys()))\n\nThese calls all start with ``request.`` because silent mammoth whistle adds a ``whistle`` object to the standard Django ``request`` object.\n\nJavaScript API\n==============\n\nThe JavaScript API is similar to the above.\n\n.. code-block:: javascript\n\n\twhistle('Edit dialog box open')\n\n``whistle`` takes an unlimited number of arguments. Each argument is added to the whistle.\n\nBot detection\n=============\n\nBot traffic is recorded and then hidden when viewing whistles. This \n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "A super-simple user analytics tool that tracks user behaviour based on web requests to your Django app.",
"version": "2.2",
"project_urls": {
"Bug Tracker": "https://github.com/benopotamus/django-silent-mammoth-whistle/issues",
"Changelog": "https://github.com/benopotamus/django-silent-mammoth-whistle/blob/main/CHANGELOG.rst",
"Documentation": "https://github.com/benopotamus/django-silent-mammoth-whistle/blob/main/README.rst",
"Homepage": "https://github.com/benopotamus/django-silent-mammoth-whistle",
"Repository": "https://github.com/benopotamus/django-silent-mammoth-whistle"
},
"split_keywords": [
"django",
" analytics",
" user",
" tracking"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c9a2a7df7a3540e00d1e28e0bf8395a96e74302b5f01724948af72f837a37a71",
"md5": "e901cd62905f3939188ecc7715d479a9",
"sha256": "b9d4b596282363babff9bf6f9a853e06bd19203e9608c5bf2ab006bee422d81d"
},
"downloads": -1,
"filename": "django_silent_mammoth_whistle-2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e901cd62905f3939188ecc7715d479a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 148748,
"upload_time": "2024-12-23T04:15:35",
"upload_time_iso_8601": "2024-12-23T04:15:35.938142Z",
"url": "https://files.pythonhosted.org/packages/c9/a2/a7df7a3540e00d1e28e0bf8395a96e74302b5f01724948af72f837a37a71/django_silent_mammoth_whistle-2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a0fc76df1d2543a65e1f79f581c75742acf2e5b0d11f8820bbe62b825f265c95",
"md5": "870616c6a22ade764266693172294761",
"sha256": "f2abe84c716ff764f886a554006196c1b3440944d28a24591fbe14fef4b4b000"
},
"downloads": -1,
"filename": "django_silent_mammoth_whistle-2.2.tar.gz",
"has_sig": false,
"md5_digest": "870616c6a22ade764266693172294761",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 142144,
"upload_time": "2024-12-23T04:15:40",
"upload_time_iso_8601": "2024-12-23T04:15:40.253928Z",
"url": "https://files.pythonhosted.org/packages/a0/fc/76df1d2543a65e1f79f581c75742acf2e5b0d11f8820bbe62b825f265c95/django_silent_mammoth_whistle-2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-23 04:15:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "benopotamus",
"github_project": "django-silent-mammoth-whistle",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-silent-mammoth-whistle"
}
JSON
