dashboard/lib/static/doc/_sources/overview.txt - incubator-flagon-user-ale - Git at Google

 Overview
 ========
 The purpose of this document is to outline the design and use of the Analytic Activity Logging API for software components built in the XDATA program. The API outlined in this document are designed to support the behavioral and physiological assessment (including eye tracking) of users as they interact with XDATA tools, in service of building a better understanding of how analyst’s make use of these tools. Through the development of a common activity logging API, we can ensure that the combined XDATA team generates uniform logging of user actions and intents. Figure 1 illustrates a planned XDATA analytic tool, with software components built by multiple program teams.


 There are several uses of the Logging API that make an application- and component-independent scheme for activity logging valuable to all software components:

 - Capturing observations for evaluation metrics
 - Capturing context for physiological assessment of XDATA tools
 - Capturing analytic interests for user or task modeling
 - Capturing analyst activity for workflow or process modeling and analysis
 - Capturing context (individual or community) for resource (data or compute) utilitization and optimization

 The vision for XDATA is that each component development team implements the proposed analytic activity logging scheme into their software component to facilitate the analysis of user workflow and the matching of measured physiological data to user and software actions using the collection of events logged from all components. Since XDATA teams are asked to implement this logging scheme, there is a desire to:

 a) Make the implementation of this scheme as painless as possible.
 b) Keep the scheme general enough that it supports the variety of teams’ software approaches.
 c) Allow the scheme to collect specific details so that it can support the analysis of a wide variety of software.
 d) Ensure the scheme is generally applicable to capturing analytic process and intent, so that the effort in implementing this logging API will have utility to performers outside of XDATA program requirements, and independent of any physiological assessment.

 :ref:`The following figure <fig-diagram>` illustrates the high-level architecture employed by this proposed API. In this architecture, each software component communicates to a logging server via XMLHttpRequests, simple JSON log messages describing the user’s interaction with each component. These messages are collected and processed to create a top-level analytic model of the user’s activity.

 .. _fig-diagram:

 .. figure:: diagram.png
    :scale: 50 %
    :alt: diagram figure

    The proposed API creates a common message passing interface that allows heterogeneous software components to communicate with an activity logging engine. This engine builds a model of the user’s activity over time.

 .. The remainder of this document is organized into the following sections. Section 2 describes the motivation and requirements for logging the activities of the user. The value of these logs, and their content is described. Section 3 describes the helper libraries and how to use them within the developers tools  Section 4 describes the logging server and message format.
	Overview
	========
	The purpose of this document is to outline the design and use of the Analytic Activity Logging API for software components built in the XDATA program. The API outlined in this document are designed to support the behavioral and physiological assessment (including eye tracking) of users as they interact with XDATA tools, in service of building a better understanding of how analyst’s make use of these tools. Through the development of a common activity logging API, we can ensure that the combined XDATA team generates uniform logging of user actions and intents. Figure 1 illustrates a planned XDATA analytic tool, with software components built by multiple program teams.


	There are several uses of the Logging API that make an application- and component-independent scheme for activity logging valuable to all software components:

	- Capturing observations for evaluation metrics
	- Capturing context for physiological assessment of XDATA tools
	- Capturing analytic interests for user or task modeling
	- Capturing analyst activity for workflow or process modeling and analysis
	- Capturing context (individual or community) for resource (data or compute) utilitization and optimization

	The vision for XDATA is that each component development team implements the proposed analytic activity logging scheme into their software component to facilitate the analysis of user workflow and the matching of measured physiological data to user and software actions using the collection of events logged from all components. Since XDATA teams are asked to implement this logging scheme, there is a desire to:

	a) Make the implementation of this scheme as painless as possible.
	b) Keep the scheme general enough that it supports the variety of teams’ software approaches.
	c) Allow the scheme to collect specific details so that it can support the analysis of a wide variety of software.
	d) Ensure the scheme is generally applicable to capturing analytic process and intent, so that the effort in implementing this logging API will have utility to performers outside of XDATA program requirements, and independent of any physiological assessment.

	:ref:`The following figure <fig-diagram>` illustrates the high-level architecture employed by this proposed API. In this architecture, each software component communicates to a logging server via XMLHttpRequests, simple JSON log messages describing the user’s interaction with each component. These messages are collected and processed to create a top-level analytic model of the user’s activity.

	.. _fig-diagram:

	.. figure:: diagram.png
	:scale: 50 %
	:alt: diagram figure

	The proposed API creates a common message passing interface that allows heterogeneous software components to communicate with an activity logging engine. This engine builds a model of the user’s activity over time.

	.. The remainder of this document is organized into the following sections. Section 2 describes the motivation and requirements for logging the activities of the user. The value of these logs, and their content is described. Section 3 describes the helper libraries and how to use them within the developers tools Section 4 describes the logging server and message format.