Part of `edX code`__.
__ http://code.edx.org/
Event Tracking library |build-status|
=====================================
The ``event-tracking`` library tracks context-aware semi-structured system events.
It captures and stores events with nested data structures in order to truly
take advantage of schemaless data storage systems.
Key features:
* Multiple backends - define custom backends that can be used to persist
your event data.
* Nested contexts - allows data to be injected into events even without
having to pass around all of said data to every location where the events
are emitted.
* Django integration - provides a Django app that allows context aware events
to easily be captured by multi-threaded web applications.
* MongoDB integration - support writing events out to a mongo collection.
Example::
from eventtracking import tracker
tracker = tracker.get_tracker()
tracker.enter_context('outer', {'user_id': 10938})
tracker.emit('navigation.request', {'url': 'http://www.edx.org/some/path/1'})
with tracker.context({'user_id': 11111, 'session_id': '2987lkjdyoioey'}):
tracker.emit('navigation.request', {'url': 'http://www.edx.org/some/path/2'})
tracker.emit(
'address.create',
{
'name': 'foo',
'address': {
'postal_code': '90210',
'country': 'United States'
}
}
)
Running the above example produces the following events::
{
"name": "navigation.request",
"timestamp": ...,
"context": {
"user_id": 10938
},
"data": {
"url": "http://www.edx.org/some/path/1"
}
},
{
"name": "navigation.request",
"timestamp": ...,
"context": {
"user_id": 11111,
"session_id": "2987lkjdyoioey"
},
"data": {
"url": "http://www.edx.org/some/path/2"
}
},
{
"name": "address.create",
"timestamp": ...,
"context": {
"user_id": 10938
},
"data": {
"name": "foo",
"address": {
"postal_code": "90210",
"country": "United States"
}
}
}
Configuration
-------------
Configuration for ``event-tracking`` takes the form of a tree of backends. When a ``Tracker`` is instantiated, it creates a root ``RoutingBackend`` object using the top-level backends and processors that are passed to it. (Or in the case of the ``DjangoTracker``, the backends and processors are constructed according to the appropriate Django settings.)
In this ``RoutingBackend``, each event is first passed through the chain of processors in series, and then distributed to each backend in turn. Theoretically, these backends might be the Mongo, Segment, or logger backends, but in practice these are wrapped by another layer of ``RoutingBackend``. This allows each one to have its own set of processors that are not shared with other backends, allowing independent filtering or event emit cancellation.
Asynchronous Routing
--------------------
Considering the volume of the events being generated, we would want to avoid
processing events in the main thread that could cause delays in response
depending upon the operations and event processors.
``event-tracking`` provides a solution for this i.e. ``AsyncRoutingBackend``.
It extends ``RoutingBackend`` but performs its operations asynchronously.
It can:
* Process event through the configured processors.
* If the event is processed successfully, pass it to the configured backends.
Handling the operations asynchronously would avoid overburdening the main thread
and pass the intensive processing tasks to celery workers.
**Limitations**: Although backends for ``RoutingBackend`` can be configured
at any level of ``EVENT_TRACKING_BACKENDS`` configuration tree,
``AsyncRoutingBackend`` only supports backends defined at the root level of
``EVENT_TRACKING_BACKENDS`` setting. It is also only possible to use it
successfully from the default tracker.
An example configuration for ``AsyncRoutingBackend`` is provided below::
EVENT_TRACKING_BACKENDS = {
'caliper': {
'ENGINE': 'eventtracking.backends.async_routing.AsyncRoutingBackend',
'OPTIONS': {
'backend_name': 'caliper',
'processors': [
{
'ENGINE': 'eventtracking.processors.regex_filter.RegexFilter',
'OPTIONS':{
'filter_type': 'allowlist',
'regular_expressions': [
'edx.course.enrollment.activated',
'edx.course.enrollment.deactivated',
]
}
}
],
'backends': {
'caliper': {
'ENGINE': 'dummy.backend.engine',
'OPTIONS': {
...
}
}
},
},
},
'tracking_logs': {
...
}
...
}
Event Bus Routing
-----------------
``event-tracking`` provides a solution for routing events to the Event Bus
using the ``EventBusBackend``. It extends ``RoutingBackend`` but sends events
to the Event Bus.
It can:
* Process event through the configured processors.
* If the event is allowed via `EVENT_BUS_TRACKING_LOGS`, send it to the Event Bus.
Make sure to enable the setting: ``SEND_TRACKING_EVENT_EMITTED_SIGNAL`` to allow the
``EventBusBackend`` to send events to the Event Bus.
An example configuration for ``EventBusBackend`` is provided below::
EVENT_TRACKING_BACKENDS = {
'xapi': {
'ENGINE': 'eventtracking.backends.event_bus.EventBusBackend',
'OPTIONS': {
'backend_name': 'xapi',
'processors': [
{
'ENGINE': 'eventtracking.processors.regex_filter.RegexFilter',
'OPTIONS':{
'filter_type': 'allowlist',
'regular_expressions': [
'edx.course.enrollment.activated',
'edx.course.enrollment.deactivated',
]
}
}
],
'backends': {
'xapi': {
'ENGINE': 'dummy.backend.engine',
'OPTIONS': {
...
}
}
},
},
},
'tracking_logs': {
...
}
...
}
EVENT_BUS_TRACKING_LOGS = [
'edx.course.enrollment.activated',
'edx.course.enrollment.deactivated',
]
Roadmap
-------
In the very near future the following features are planned:
* Dynamic event documentation and event metadata - allow event emitters to
document the event types, and persist this documentation along with the
events so that it can be referenced during analysis to provide context
about what the event is and when it is emitted.
Documentation
-------------
`Latest documentation <http://event-tracking.readthedocs.org/en/latest/>`_ (Hosted on Read the Docs)
License
-------
The code in this repository is licensed under version 3 of the AGPL unless
otherwise noted.
Please see ``LICENSE.txt`` for details.
How to Contribute
-----------------
Contributions are very welcome.
Please read `How To Contribute <https://github.com/openedx/edx-platform/wiki/How-To-Contribute>`_ for details.
Reporting Security Issues
-------------------------
Please do not report security issues in public. Please email security@openedx.org
Mailing List and IRC Channel
----------------------------
You can discuss this code on the `edx-code Google Group`__ or in the
``edx-code`` IRC channel on Freenode.
__ https://groups.google.com/forum/#!forum/edx-code
.. |build-status| image:: https://github.com/openedx/event-tracking/workflows/Python%20CI/badge.svg?branch=master
:target: https://github.com/openedx/event-tracking/actions?query=workflow%3A%22Python+CI%22
Raw data
{
"_id": null,
"home_page": "https://github.com/openedx/event-tracking",
"name": "event-tracking",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "edX",
"author_email": "oscm@edx.org",
"download_url": "https://files.pythonhosted.org/packages/4a/51/d8cf221b05e1b44c425900a413aa83c6bb87db3b9fa3474553bfc2867b32/event-tracking-2.4.0.tar.gz",
"platform": null,
"description": "Part of `edX code`__.\n\n__ http://code.edx.org/\n\nEvent Tracking library |build-status|\n=====================================\n\nThe ``event-tracking`` library tracks context-aware semi-structured system events.\nIt captures and stores events with nested data structures in order to truly\ntake advantage of schemaless data storage systems.\n\nKey features:\n\n* Multiple backends - define custom backends that can be used to persist\n your event data.\n* Nested contexts - allows data to be injected into events even without\n having to pass around all of said data to every location where the events\n are emitted.\n* Django integration - provides a Django app that allows context aware events\n to easily be captured by multi-threaded web applications.\n* MongoDB integration - support writing events out to a mongo collection.\n\nExample::\n\n from eventtracking import tracker\n\n tracker = tracker.get_tracker()\n tracker.enter_context('outer', {'user_id': 10938})\n tracker.emit('navigation.request', {'url': 'http://www.edx.org/some/path/1'})\n\n with tracker.context({'user_id': 11111, 'session_id': '2987lkjdyoioey'}):\n tracker.emit('navigation.request', {'url': 'http://www.edx.org/some/path/2'})\n\n tracker.emit(\n 'address.create',\n {\n 'name': 'foo',\n 'address': {\n 'postal_code': '90210',\n 'country': 'United States'\n }\n }\n )\n\nRunning the above example produces the following events::\n\n {\n \"name\": \"navigation.request\",\n \"timestamp\": ...,\n \"context\": {\n \"user_id\": 10938\n },\n \"data\": {\n \"url\": \"http://www.edx.org/some/path/1\"\n }\n },\n {\n \"name\": \"navigation.request\",\n \"timestamp\": ...,\n \"context\": {\n \"user_id\": 11111,\n \"session_id\": \"2987lkjdyoioey\"\n },\n \"data\": {\n \"url\": \"http://www.edx.org/some/path/2\"\n }\n },\n {\n \"name\": \"address.create\",\n \"timestamp\": ...,\n \"context\": {\n \"user_id\": 10938\n },\n \"data\": {\n \"name\": \"foo\",\n \"address\": {\n \"postal_code\": \"90210\",\n \"country\": \"United States\"\n }\n }\n }\n\n\nConfiguration\n-------------\n\nConfiguration for ``event-tracking`` takes the form of a tree of backends. When a ``Tracker`` is instantiated, it creates a root ``RoutingBackend`` object using the top-level backends and processors that are passed to it. (Or in the case of the ``DjangoTracker``, the backends and processors are constructed according to the appropriate Django settings.)\n\nIn this ``RoutingBackend``, each event is first passed through the chain of processors in series, and then distributed to each backend in turn. Theoretically, these backends might be the Mongo, Segment, or logger backends, but in practice these are wrapped by another layer of ``RoutingBackend``. This allows each one to have its own set of processors that are not shared with other backends, allowing independent filtering or event emit cancellation.\n\n\nAsynchronous Routing\n--------------------\n\nConsidering the volume of the events being generated, we would want to avoid\nprocessing events in the main thread that could cause delays in response\ndepending upon the operations and event processors.\n\n``event-tracking`` provides a solution for this i.e. ``AsyncRoutingBackend``.\nIt extends ``RoutingBackend`` but performs its operations asynchronously.\n\nIt can:\n\n* Process event through the configured processors.\n* If the event is processed successfully, pass it to the configured backends.\n\nHandling the operations asynchronously would avoid overburdening the main thread\nand pass the intensive processing tasks to celery workers.\n\n**Limitations**: Although backends for ``RoutingBackend`` can be configured\nat any level of ``EVENT_TRACKING_BACKENDS`` configuration tree,\n``AsyncRoutingBackend`` only supports backends defined at the root level of\n``EVENT_TRACKING_BACKENDS`` setting. It is also only possible to use it\nsuccessfully from the default tracker.\n\nAn example configuration for ``AsyncRoutingBackend`` is provided below::\n\n EVENT_TRACKING_BACKENDS = {\n 'caliper': {\n 'ENGINE': 'eventtracking.backends.async_routing.AsyncRoutingBackend',\n 'OPTIONS': {\n 'backend_name': 'caliper',\n 'processors': [\n {\n 'ENGINE': 'eventtracking.processors.regex_filter.RegexFilter',\n 'OPTIONS':{\n 'filter_type': 'allowlist',\n 'regular_expressions': [\n 'edx.course.enrollment.activated',\n 'edx.course.enrollment.deactivated',\n ]\n }\n }\n ],\n 'backends': {\n 'caliper': {\n 'ENGINE': 'dummy.backend.engine',\n 'OPTIONS': {\n ...\n }\n }\n },\n },\n },\n 'tracking_logs': {\n ...\n }\n ...\n }\n\n\nEvent Bus Routing\n-----------------\n\n``event-tracking`` provides a solution for routing events to the Event Bus\nusing the ``EventBusBackend``. It extends ``RoutingBackend`` but sends events\nto the Event Bus.\n\nIt can:\n\n* Process event through the configured processors.\n* If the event is allowed via `EVENT_BUS_TRACKING_LOGS`, send it to the Event Bus.\n\nMake sure to enable the setting: ``SEND_TRACKING_EVENT_EMITTED_SIGNAL`` to allow the\n``EventBusBackend`` to send events to the Event Bus.\n\nAn example configuration for ``EventBusBackend`` is provided below::\n\n EVENT_TRACKING_BACKENDS = {\n 'xapi': {\n 'ENGINE': 'eventtracking.backends.event_bus.EventBusBackend',\n 'OPTIONS': {\n 'backend_name': 'xapi',\n 'processors': [\n {\n 'ENGINE': 'eventtracking.processors.regex_filter.RegexFilter',\n 'OPTIONS':{\n 'filter_type': 'allowlist',\n 'regular_expressions': [\n 'edx.course.enrollment.activated',\n 'edx.course.enrollment.deactivated',\n ]\n }\n }\n ],\n 'backends': {\n 'xapi': {\n 'ENGINE': 'dummy.backend.engine',\n 'OPTIONS': {\n ...\n }\n }\n },\n },\n },\n 'tracking_logs': {\n ...\n }\n ...\n }\n\n EVENT_BUS_TRACKING_LOGS = [\n 'edx.course.enrollment.activated',\n 'edx.course.enrollment.deactivated',\n ]\n\nRoadmap\n-------\n\nIn the very near future the following features are planned:\n\n* Dynamic event documentation and event metadata - allow event emitters to\n document the event types, and persist this documentation along with the\n events so that it can be referenced during analysis to provide context\n about what the event is and when it is emitted.\n\n\nDocumentation\n-------------\n\n`Latest documentation <http://event-tracking.readthedocs.org/en/latest/>`_ (Hosted on Read the Docs)\n\n\nLicense\n-------\n\nThe code in this repository is licensed under version 3 of the AGPL unless\notherwise noted.\n\nPlease see ``LICENSE.txt`` for details.\n\n\nHow to Contribute\n-----------------\n\nContributions are very welcome.\n\nPlease read `How To Contribute <https://github.com/openedx/edx-platform/wiki/How-To-Contribute>`_ for details.\n\nReporting Security Issues\n-------------------------\n\nPlease do not report security issues in public. Please email security@openedx.org\n\nMailing List and IRC Channel\n----------------------------\n\nYou can discuss this code on the `edx-code Google Group`__ or in the\n``edx-code`` IRC channel on Freenode.\n\n__ https://groups.google.com/forum/#!forum/edx-code\n\n.. |build-status| image:: https://github.com/openedx/event-tracking/workflows/Python%20CI/badge.svg?branch=master\n :target: https://github.com/openedx/event-tracking/actions?query=workflow%3A%22Python+CI%22\n",
"bugtrack_url": null,
"license": "AGPLv3 License",
"summary": "A simple event tracking system.",
"version": "2.4.0",
"project_urls": {
"Homepage": "https://github.com/openedx/event-tracking"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4429d9fcb9d28120d60d13b4dc354af0296e69ce048aee911a5db0d78305faab",
"md5": "65f04c54660d1c5d953d8cd241248f4b",
"sha256": "4163fe97ba06b83fd8be6cbed54dc96ef9c0f0eb0d9788c9c6f62f9d0b6bd860"
},
"downloads": -1,
"filename": "event_tracking-2.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "65f04c54660d1c5d953d8cd241248f4b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 54664,
"upload_time": "2024-04-09T15:41:46",
"upload_time_iso_8601": "2024-04-09T15:41:46.222917Z",
"url": "https://files.pythonhosted.org/packages/44/29/d9fcb9d28120d60d13b4dc354af0296e69ce048aee911a5db0d78305faab/event_tracking-2.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a51d8cf221b05e1b44c425900a413aa83c6bb87db3b9fa3474553bfc2867b32",
"md5": "feb550f463f8131065c4d4dbd1e9086e",
"sha256": "62e54788b9d6cf0c9f1205e38ed87708f5fdf8ab4e8a2c51fb69031fa58c1b53"
},
"downloads": -1,
"filename": "event-tracking-2.4.0.tar.gz",
"has_sig": false,
"md5_digest": "feb550f463f8131065c4d4dbd1e9086e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 42466,
"upload_time": "2024-04-09T15:41:48",
"upload_time_iso_8601": "2024-04-09T15:41:48.254531Z",
"url": "https://files.pythonhosted.org/packages/4a/51/d8cf221b05e1b44c425900a413aa83c6bb87db3b9fa3474553bfc2867b32/event-tracking-2.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-09 15:41:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openedx",
"github_project": "event-tracking",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "event-tracking"
}
JSON
