API Documentation

Apache UserALE.PyQt5 intercepts all application events by letting the developer install an event filter in their PyQt5 application to generate detailed user logs. Apache UserALE.PyQt5 does not capture system level logs or events generated by a non-user (a.k.a. system and signals sent between QObjects).

Apache UserALE.PyQt5

class userale.ale.Ale(output='userale.log', user=None,
session=None, toolname=None, toolversion=None,
keylog=False, interval=5000, resolution=100, shutoff=[])

Bases: PyQt5.QtCore.QObject

Parameters:

output – [str] The file or url path to which logs will be sent

user – [str] Identifier for the user of the application

session – [str] Session tag to track same user with multiple sessions. If a session is not provided, one will be created

toolname – [str] The application name

toolversion – [str] The application version

keylog – [bool] Should detailed key logs be recorded. Default is False

interval – [int] The minimum time interval in ms between batch transmission of logs. Default is 5000ms.

resolution – [int] Delay in ms between instances of high frequency logs like mousemoves, scrolls, etc. Default is 100ms (10Hz).

shutoff – [list] Turn off logging for specific events

An example log will appear like this:

  {
      'target': 'testLineEdit',
      'path': ['Example', 'testLineEdit'],
      'clientTime': '2016-08-03 16:12:03.460573',
      'location': {'x': 82, 'y': 0},
      'type': 'mousemove',
      'userAction': 'true',
      'details' : {},
      'userId': 'userABC1234',
      'session': '5ee42ccc-852c-44d9-a937-28d7901e4ead',
      'toolName': 'myApplication',
      'toolVersion': '3.5.0',
      'useraleVersion': '0.1.0'
  }

aggregate()

Sample high frequency logs at self.resolution. High frequency logs are consolidated down to a single log event to be emitted later

cleanup()

Clean up any dangling logs in self.logs or self.hlogs

dump()

Write log data to file

eventFilter(object, event)

Filters events for the watched widget.

Parameters:

object – [QObject] The object being watched.

event – [QEvent] The event triggered by a user action.

Returns:

[bool] Propagate filter up if other objects needs to be handled

getClientTime()

Capture the time the event was captured in milliseconds since the UNIX epoch (January 1, 1970 00:00:00 UTC)

Returns:

[str] String representation of the time the event was captured.

getLocation(event)

Grab the x and y position of the mouse cursor, relative to the widget that received the event.

Parameters:

event – [QEvent] The base class for all event classes.

Returns:

[dict] A dictionary representation of the x and y positions of the mouse cursor.

getPath(object)

Generate the entire object hierachy from root to leaf node.

Parameters:

object – [QObject] The base class for all Qt objects.

Returns:

[list] List of QObjects.

getSelector(object)

Get target object’s name (object defined by user or object’s meta class name).

Parameters:

object – [QObject] The base class for all Qt objects.

Returns:

[str] The Qt object’s name

getSender(object)

Fetch the QObject who triggered the event

Parameters:

object – [QObject] The object being watched.

Returns:

[QObject] The QObject

handleDragEvents(event_type, event, object)

Returns the userale log representing all drag events.

Parameters:

event_type – [str] The string representation of the type of event being triggered by the user.

event – [QEvent] The base class for all event classes.

object – [QObject] The base class for all Qt objects.

Returns:

[dict] A userale log describing a drag event.

handleKeyEvents(event_type, event, object)

Returns the userale log representing all key events, including key name and key code.

Parameters:

event_type – [str] The string representation of the type of event being triggered by the user.

event – [QEvent] The base class for all event classes.

object – [QObject] The base class for all Qt objects.

Returns:

[dict] A userale log describing a key event.

handleMouseEvents(event_type, event, object)

Returns the userale log representing all mouse event data.

Parameters:

event_type – [str] The string representation of the type of event being triggered by the user.

event – [QEvent] The base class for all event classes.

object – [QObject] The base class for all Qt objects.

Returns:

[dict] A userale log describing a mouse event.

handleMoveEvents(event_type, event, object)

Returns the userale log representing all move events.

Parameters:

event_type – [str] The string representation of the type of event being triggered by the user.

event – [QEvent] The base class for all event classes.

object – [QObject] The base class for all Qt objects.

Returns:

[dict] A userale log describing a drag event.

handleResizeEvents(event_type, event, object)

Returns the userale log representing all resize events.

Parameters:

event_type – [str] The string representation of the type of event being triggered by the user.

event – [QEvent] The base class for all event classes.

object – [QObject] The base class for all Qt objects. Returns:

[dict] A userale log describing a resize event.

handleScrollEvents(event_type, event, object)

Returns the userale log representing all scroll events.

Parameters:

event_type – [str] The string representation of the type of event being triggered by the user.

event – [QEvent] The base class for all event classes.

object – [QObject] The base class for all Qt objects.

Returns:

[dict] A userale log describing a scroll event.

timerEvent(event)

Routinely dump data to file or send over the network

Parameters:

object – [list] List of events

Returns:

[void] Emit events to file

Apache Flagon