Django Trackman
===============
Django Trackman helps with tracking and logging.
Features
--------
- Customizable models: You'll have base models and an admin class mixins
that you can extend to define your own tracking models.
- Separate database: You can decide to use a separate database for your tracking data, as it could
grow fast. A database router will help you implement the Django multiple database feature.
- Loose coupling: The tracking table is not related to you application table with foreign keys.
This ensures that your tracking data is kept independent of your application data.
- Admin action tracking: You can enable tracking of Django admin actions.
- API Endpoint: You can define django-rest-framework views to create API endpoints. This can be
used to track actions made through API calls.
Installation
------------
.. code-block:: shell
pip install django-trackman
Add 'trackman' to your INSTALLED_APPS in Django's settings:
.. code-block:: python
INSTALLED_APPS = (
...
'trackman',
...
)
Then enable trackman by setting the variable `TRACKMAN_ENABLED` to `True`.
Action Tracking Models
----------------------
Django Trackman can be used to create custom tracking models.
Here's an example of a model class that extends Django Trackman's `TrackingActionModel``:
.. code-block:: python
from trackman.models import TrackingActionModel
from django.db import models
class TrackingAction(TrackingActionModel):
team = models.CharField("Team", max_length=256, blank=True)
def __str__(self):
return f"Actor: {self.actor}, Action: {self.action}, Time: {self.created}"
class Meta:
verbose_name = "Action Log"
verbose_name_plural = "Action Logs"
How Django Trackman would know that this model should be used by default for tracking
your actions ? You'll need to instruct it by defining a default tracking model in
your settings.
.. code-block:: python
TRACKMAN_MODELS = {
"default": "tracking.TrackingAction",
"data-quality": "tracking.DataQualityTracking",
}
Here, you'll notice that we have also defined a additional tracking model for data
quality tracking.
Base Tracking Models
--------------------
If your models are not action oriented, you can always extend the `TrackingBaseModel`
that's an empty abstract model that only serves as a way to let Trackman know that
your model should be consider as a tracking model and thus should be taken into account
when during database routing.
Admin
-----
For managing your tracking models in Django admin, Django Trackman provides the mix-in class
`TrackingModelAdminMixin`.
.. code-block:: python
from django.contrib import admin
from trackman.admin import TrackingModelAdminMixin
from .models import TrackingAction
class TrackingActionAdmin(TrackingModelAdminMixin, admin.ModelAdmin):
list_display = [
"id",
"actor",
"team",
"action",
"object",
"target",
"description",
"created",
]
search_fields = ["actor", "team"] + TrackingModelAdminMixin.action_log_search_fields
list_filter = ["team", "action"]
if settings.TRACKMAN_ENABLED:
admin.site.register(TrackingAction, TrackingActionAdmin)
Tracking on a separate database
-------------------------------
When you want to isolate tracking data from your main application data for performance,
maintenance or data integrity reasons, you could route tracking database operations to a
separate database.
Django's multiple database feature allows you to use more than one database in your project.
It provides the flexibility to specify which models use which database - that's defined by a
router. Django Trackman uses that feature to isolate you tracking data from your application
data.
You will first need to instruct in your project's settings, the database alias that should be
used.
.. code-block:: python
TRACKMAN_DATABASE_ALIAS = "tracking"
Then define the database accesses.
.. code-block:: python
DATABASES = {
"default": {
'ENGINE': 'django.db.backends.<app-database>',
'NAME': <app-database-name>,
'USER': <-app-database-user>,
'PASSWORD': <-app-database-password>,
'HOST': <-app-database-host>,
'PORT': <-app-database-port>,
},
}
if TRACKMAN_ENABLED:
DATABASE_ROUTERS = ["trackman.db_routers.TrackmanDatabaseRouter"]
DATABASES[TRACKMAN_DATABASE_ALIAS] = {
'ENGINE': 'django.db.backends.<tracking-db>',
'NAME': <tracking-database-name>,
'USER': <tracking-database-user>,
'PASSWORD': <tracking-database-password>,
'HOST': <tracking-database-host>,
'PORT': <tracking-database-port>,
}
If you are using a tool like `dj-database-url` with environnement variables:
.. code-block:: python
from django.urls import dj_database_url.parse
DATABASES = {"default": dj_database_url.parse(env("APP_DATABASE_URL"))}
if TRACKMAN_ENABLED:
DATABASE_ROUTERS = ["trackman.db_routers.TrackingDatabaseRouter"]
db_url = env("TRACKING_DATABASE_URL")
DATABASES[TRACKMAN_DATABASE_ALIAS] = dj_database_url.parse(db_url)
Tracking admin action
---------------------
Django Trackman, allows you to track Django admin actions - the actions that
the admin users are performing.
Setting Up Django Trackman
The main file is trackman/signals.py, and it requires importing in some AppConfig's
ready method.
Let's suppose that you have a backoffice app that you can use to setup signals.
.. code-block:: python
from django.apps import AppConfig
import sys
class BackofficeConfig(AppConfig):
name = "backoffice"
verbose_name = "Backoffice"
def ready(self):
if "migrate" not in sys.argv:
import trackman.signals # noqa
As a consequence, all admin actions will be copied to you tracking table.
API End-point
-------------
Django Trackman provides a mixin you can use with Django Rest Framework's ViewSet to create an API end-point
for your application to track actions. This could be useful for tracking front-end actions.
Here's how you can use TrackingViewSetMixin in a Django REST ViewSet for action tracking:
.. code-block:: python
from rest_framework import viewsets
from trackman.api import TrackingViewSetMixin
class ActionTrackingViewSet(TrackingViewSetMixin, viewsets.ViewSet):
model_alias = "default"
def clean_action_details(self, action_details):
# Do some clean-up here...
cleaned_data = action_details.copy()
return cleaned_data
The `model_alias` points out which Django Trackman model alias to be used for saving the tracking data.
You'll need to add this new ViewSet ActionTrackingViewSet to your url configuration to have it active.
Raw data
{
"_id": null,
"home_page": "https://github.com/lazybird/django-trackman/",
"name": "django-trackman",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "trackman django log logging tracking activity",
"author": "",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/05/08/0d8e7ad231189a802492611cb51a469523876e491bc4065f67e9cdc1cddb/django-trackman-0.1.1.tar.gz",
"platform": null,
"description": "Django Trackman\n===============\n\n\nDjango Trackman helps with tracking and logging.\n\n\nFeatures\n--------\n\n- Customizable models: You'll have base models and an admin class mixins\n that you can extend to define your own tracking models.\n\n- Separate database: You can decide to use a separate database for your tracking data, as it could\n grow fast. A database router will help you implement the Django multiple database feature.\n\n- Loose coupling: The tracking table is not related to you application table with foreign keys.\n This ensures that your tracking data is kept independent of your application data.\n\n- Admin action tracking: You can enable tracking of Django admin actions.\n\n- API Endpoint: You can define django-rest-framework views to create API endpoints. This can be \n used to track actions made through API calls.\n\n\nInstallation\n------------\n\n.. code-block:: shell\n\n pip install django-trackman\n\n\nAdd 'trackman' to your INSTALLED_APPS in Django's settings:\n\n\n.. code-block:: python\n\n INSTALLED_APPS = (\n ...\n 'trackman',\n ...\n )\n\n\nThen enable trackman by setting the variable `TRACKMAN_ENABLED` to `True`.\n\n\nAction Tracking Models\n----------------------\n\nDjango Trackman can be used to create custom tracking models.\nHere's an example of a model class that extends Django Trackman's `TrackingActionModel``:\n\n\n.. code-block:: python\n\n from trackman.models import TrackingActionModel\n from django.db import models\n\n class TrackingAction(TrackingActionModel):\n team = models.CharField(\"Team\", max_length=256, blank=True)\n\n def __str__(self):\n return f\"Actor: {self.actor}, Action: {self.action}, Time: {self.created}\"\n\n class Meta:\n verbose_name = \"Action Log\"\n verbose_name_plural = \"Action Logs\"\n\n\n\nHow Django Trackman would know that this model should be used by default for tracking\nyour actions ? You'll need to instruct it by defining a default tracking model in\nyour settings.\n\n.. code-block:: python\n\n TRACKMAN_MODELS = {\n \"default\": \"tracking.TrackingAction\",\n \"data-quality\": \"tracking.DataQualityTracking\",\n }\n\nHere, you'll notice that we have also defined a additional tracking model for data\nquality tracking.\n\n\nBase Tracking Models\n--------------------\n\nIf your models are not action oriented, you can always extend the `TrackingBaseModel`\nthat's an empty abstract model that only serves as a way to let Trackman know that\nyour model should be consider as a tracking model and thus should be taken into account\nwhen during database routing.\n\n\nAdmin\n-----\n\nFor managing your tracking models in Django admin, Django Trackman provides the mix-in class\n`TrackingModelAdminMixin`.\n\n.. code-block:: python\n\n from django.contrib import admin\n from trackman.admin import TrackingModelAdminMixin\n from .models import TrackingAction\n\n class TrackingActionAdmin(TrackingModelAdminMixin, admin.ModelAdmin):\n list_display = [\n \"id\",\n \"actor\",\n \"team\",\n \"action\",\n \"object\",\n \"target\",\n \"description\",\n \"created\",\n ]\n search_fields = [\"actor\", \"team\"] + TrackingModelAdminMixin.action_log_search_fields\n list_filter = [\"team\", \"action\"]\n\n if settings.TRACKMAN_ENABLED:\n admin.site.register(TrackingAction, TrackingActionAdmin)\n\n\nTracking on a separate database\n-------------------------------\n\nWhen you want to isolate tracking data from your main application data for performance,\nmaintenance or data integrity reasons, you could route tracking database operations to a\nseparate database.\n\n\nDjango's multiple database feature allows you to use more than one database in your project.\nIt provides the flexibility to specify which models use which database - that's defined by a\nrouter. Django Trackman uses that feature to isolate you tracking data from your application\ndata.\n\n\nYou will first need to instruct in your project's settings, the database alias that should be\nused.\n\n\n.. code-block:: python\n\n TRACKMAN_DATABASE_ALIAS = \"tracking\"\n\n\nThen define the database accesses.\n\n.. code-block:: python\n\n DATABASES = {\n \"default\": {\n 'ENGINE': 'django.db.backends.<app-database>',\n 'NAME': <app-database-name>,\n 'USER': <-app-database-user>,\n 'PASSWORD': <-app-database-password>,\n 'HOST': <-app-database-host>,\n 'PORT': <-app-database-port>,\n },\n }\n\n if TRACKMAN_ENABLED:\n DATABASE_ROUTERS = [\"trackman.db_routers.TrackmanDatabaseRouter\"]\n DATABASES[TRACKMAN_DATABASE_ALIAS] = {\n 'ENGINE': 'django.db.backends.<tracking-db>',\n 'NAME': <tracking-database-name>,\n 'USER': <tracking-database-user>,\n 'PASSWORD': <tracking-database-password>,\n 'HOST': <tracking-database-host>,\n 'PORT': <tracking-database-port>,\n }\n\n\nIf you are using a tool like `dj-database-url` with environnement variables:\n\n\n.. code-block:: python\n\n from django.urls import dj_database_url.parse\n\n DATABASES = {\"default\": dj_database_url.parse(env(\"APP_DATABASE_URL\"))}\n\n if TRACKMAN_ENABLED:\n DATABASE_ROUTERS = [\"trackman.db_routers.TrackingDatabaseRouter\"]\n db_url = env(\"TRACKING_DATABASE_URL\")\n DATABASES[TRACKMAN_DATABASE_ALIAS] = dj_database_url.parse(db_url)\n\n\nTracking admin action\n---------------------\n\n\nDjango Trackman, allows you to track Django admin actions - the actions that\nthe admin users are performing.\n\nSetting Up Django Trackman\nThe main file is trackman/signals.py, and it requires importing in some AppConfig's\nready method.\n\nLet's suppose that you have a backoffice app that you can use to setup signals.\n\n\n.. code-block:: python\n\n from django.apps import AppConfig\n import sys\n\n class BackofficeConfig(AppConfig):\n name = \"backoffice\"\n verbose_name = \"Backoffice\"\n\n def ready(self):\n if \"migrate\" not in sys.argv:\n import trackman.signals # noqa\n\n\nAs a consequence, all admin actions will be copied to you tracking table.\n\n\nAPI End-point\n-------------\n\nDjango Trackman provides a mixin you can use with Django Rest Framework's ViewSet to create an API end-point\nfor your application to track actions. This could be useful for tracking front-end actions.\n\nHere's how you can use TrackingViewSetMixin in a Django REST ViewSet for action tracking:\n\n.. code-block:: python\n\n from rest_framework import viewsets\n from trackman.api import TrackingViewSetMixin\n\n class ActionTrackingViewSet(TrackingViewSetMixin, viewsets.ViewSet):\n model_alias = \"default\"\n\n def clean_action_details(self, action_details):\n # Do some clean-up here...\n cleaned_data = action_details.copy()\n return cleaned_data\n\n\n\nThe `model_alias` points out which Django Trackman model alias to be used for saving the tracking data.\n\nYou'll need to add this new ViewSet ActionTrackingViewSet to your url configuration to have it active.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Django Trackman helps with tracking and logging.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/lazybird/django-trackman/"
},
"split_keywords": [
"trackman",
"django",
"log",
"logging",
"tracking",
"activity"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9cbcf81b91d8b79af234e5897067650e25624c66d4ba1204b7d7801ffdca8bb4",
"md5": "8dce7fecb333d04362c099a663fa0546",
"sha256": "26cc32cc98c0473978beb0b4713be5f25cb8544debb7fe0c762b9b5e9db7b4de"
},
"downloads": -1,
"filename": "django_trackman-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8dce7fecb333d04362c099a663fa0546",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12722,
"upload_time": "2023-10-04T09:44:04",
"upload_time_iso_8601": "2023-10-04T09:44:04.152698Z",
"url": "https://files.pythonhosted.org/packages/9c/bc/f81b91d8b79af234e5897067650e25624c66d4ba1204b7d7801ffdca8bb4/django_trackman-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "05080d8e7ad231189a802492611cb51a469523876e491bc4065f67e9cdc1cddb",
"md5": "9f160b6be20aa3a39335c83170160e5a",
"sha256": "b5042ffac5d16a61a48b8ad7c1c5ea1ce2d57aabac5286c0ceff8463fe2eba49"
},
"downloads": -1,
"filename": "django-trackman-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "9f160b6be20aa3a39335c83170160e5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9197,
"upload_time": "2023-10-04T09:44:07",
"upload_time_iso_8601": "2023-10-04T09:44:07.167534Z",
"url": "https://files.pythonhosted.org/packages/05/08/0d8e7ad231189a802492611cb51a469523876e491bc4065f67e9cdc1cddb/django-trackman-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-04 09:44:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lazybird",
"github_project": "django-trackman",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-trackman"
}
JSON
