API Reference


A simple event tracking library


Track application events. Supports persisting events to multiple backends.

Best Practices:

  • It is recommended that event types are namespaced using dot notation to avoid naming collisions, similar to DNS names. For example: org.edx.video.stop, edu.mit.audio.stop
  • Avoid using event type names that may cause collisions. The burden is on the analyst to decide whether your event is equivalent to another and should be grouped accordingly etc.
  • Do not emit events that you don’t own. This could negatively impact the analysis of the event stream. If you suspect your event is equivalent to another, say so in your documenation, and the analyst can decide whether or not to group them.
class eventtracking.tracker.Tracker(backends=None, context_locator=None, processors=None)[source]

Bases: object

Track application events. Holds references to a set of backends that will be used to persist any events that are emitted.


The dictionary of registered backends

context(name, ctx)[source]

Execute the block with the given context applied. This manager ensures that the context is removed even if an exception is raised within the context.

emit(name=None, data=None)[source]

Emit an event annotated with the UTC time when this function was called.

name is a unique identification string for an event that has
already been registered.
data is a dictionary mapping field names to the value to include in the event.
Note that all values provided must be serializable.
enter_context(name, ctx)[source]

Enter a named context. Any events emitted after calling this method will contain all of the key-value pairs included in ctx unless overridden by a context that is entered after this call.


Exit a named context. This will remove all key-value pairs associated with this context from any events emitted after it is removed.


Gets the backend that was configured with name


The thread local context for this tracker.


The list of registered processors


Create a new dictionary that corresponds to the union of all of the contexts that have been entered but not exited at this point.

eventtracking.tracker.emit(name=None, data=None)[source]

Calls Tracker.emit on the default global tracker


Gets a named tracker. Defaults to the default global tracker. Raises a KeyError if no such tracker has been registered by previously calling register_tracker.

eventtracking.tracker.register_tracker(tracker, name='default')[source]

Makes a tracker globally accessible. Providing no name parameter allows you to register the global default tracker that will be used by subsequent calls to tracker.emit.


Strategies for locating contexts. Allows for arbitrarily complex caching and context differentiation strategies.

All context locators must implement a get method that returns an OrderedDict-like object.

class eventtracking.locator.DefaultContextLocator[source]

Bases: object

One-to-one mapping between contexts and trackers. Every tracker will get a new context instance and it will always be returned by this locator.


Get a reference to the context.

class eventtracking.locator.ThreadLocalContextLocator[source]

Bases: object

Returns a different context depending on the thread that the locator was called from. Thus, contexts can be isolated from one another on thread boundaries.

Note that this makes use of threading.local(), which is typically monkey-patched by alternative python concurrency frameworks (like gevent).

Calls to threading.local() are delayed until first usage in order to give the third-party concurrency libraries an opportunity to monkey monkey patch it.


Return a reference to a thread-specific context