The Activity sensor data type is designed to represent editing "activities", or events such as opening a file, closing a file, or editing a file. Table 25.1, “Activity SDT attributes” documents the attributes of this sensor data type.
Table 25.1. Activity SDT attributes
| Attribute | Description |
|---|---|
| tstamp | The UTC time at which this data was collected. |
| tool | A string indicating the tool that collected this data, such as "Eclipse" or "Emacs". |
| type | The type of activity, such as "Close File" or "State Change". The ActivityType class provides a dictionary of activity types that can be used by editor sensors. |
| file | A file string concerning this activity, which in most cases is the absolute path of the file involved in this event. It is an empty string when the activity has no associated file. |
Activity SDT data is always generated by editor sensors such as the sensors for Eclipse, Emacs, Vim, JBuilder, Visual Studio, and so forth. Some of these sensors might also generate data associated with other sensor data types (for example, UnitTest). Activity SDT data is not currently generated by non-editor sensors.
All editor sensors are required to implement the "State Change" activity event type, and they are all required to implement it in a similar way so that this data can be interpreted uniformly regardless of the editor sensor that generated it. In brief, the "State Change" event type indicates that the editor was in active use during the preceding interval of time indicated by the HACKYSTAT_STATECHANGE_INTERVAL value provided in sensor.properties (and which defaults to 30 seconds). The State Change event is sent to the server if the active buffer associated with a file changed in size during the previous interval in time, or if a different file is now associated with the active buffer compared to the one in the previous interval. Thus, the State Change event indicates that the use was "actively" using the editor during the preceding interval of time, as well as the file that the user was "actively" modifying during this period of active usage.
The State Change activity type solves one of the common problems associated with time tracking: how do you tell when the user has gone off to lunch but left their editor running? In this case, the timer process that wakes up every HACKYSTAT_STATECHANGE_INTERVAL to check the active buffer will find that the size of the buffer is not changing, and therefore not record a State Change event.
![[Note]](gfx/admonitions/note.gif) | Note |
|---|---|
To help guarantee that the State Change event is collected uniformly by all editor sensors, special support for this command is provided in the SensorShell. To collect State Change events, sensors simply have to implement a timer-based process that wakes up every HACKYSTAT_STATECHANGE_INTERVAL, determines the current active buffer and its size, and sends that to the SensorShell using the Activity#statechange command and passing the current file name and size. This command will compare the current statechange data against the last data provided, and only generate the State Change event if the current data has changed relative to the data collected during the last interval. | |
A sensor for an editor is only responsible for collecting and sending raw Activity data (including State Change) events to the server. It is useful, however, to understand the principal usage of Activity data, which is to abstract the sequence of State Change events into a representation of developer activity called Active Time.
The Active Time representation begins by dividing each 24 hour day into 288 five minute intervals. For each five minute interval, if at least one State Change event exists for that interval, then the user is assumed to have been active for that entire five minute interval. To determine the focus of attention during that five minute interval, the file associated with each State Change event counts as a vote, and the file getting the most votes during that five minute interval becomes the "Most Active File" for that five minute interval, and is counted as the single file that the user was working on for that entire five minute period.
To display the Activity data associated with your account, use the "List Sensor Data" command in the Extras page. Figure 25.1, “ Activity data with List Sensor Data ” illustrates an example invocation of this command.
A more abstract view of your Activity data is provided in the Daily Diary, which divides the day into 288 five minute intervals and which can show the total number of Activity SDT data entries collected during an interval, the Most Active File during each five minute interval (calculated as the file, if any, that had the most State Change events associated with it), and other useful information. Figure 25.2, “ Activity data with Daily Diary ” illustrates an example invocation of this command.
