The Emacs sensor collects data regarding developer activities using the Emacs editor. The Emacs sensor can represent this data using the Activity, DevEvent, and BuffTrans sensor data types, documented in Section 25.2, “Activity”, Section 25.10, “DevEvent”, and Section 25.3, “BuffTrans”, respectively.
The most important type of sensor data collected by the Emacs sensor for analysis purposes is DevEvents, and so Table 26.6, “Emacs sensor DevEvent sensor data” documents the DevEvent types collected by Emacs. Note that the "type" entryattribute is for Emacs DevEvent sensor data is always "Edit". To distinguish the various actions, the Emacs sensor uses the optional property "subtype".
Table 26.6. Emacs sensor DevEvent sensor data
| type | subtype | description and additional properties |
|---|---|---|
| Edit | OpenFile | Generated when a new file is opened. Path is the file being opened. No optional properties. |
| Edit | CloseFile | Generated when a file is closed. Path is the file being closed. No optional properties. |
| Edit | SaveFile | Generated when a file is saved. Path is the file being saved. No optional properties. |
| Edit | BufferTransition | Generated when the user switches buffers. Path is the new file being visited. The user must enable BufferTransition data collection for this type of DevEvent to be collected. No optional properties. |
| Edit | StateChange | Generated when a file is under active modification. Uses a timer-based process to wake up every "state change interval" and check to see if the current buffer has been modified. If so, the Edit event is generated. |
Emacs is "the extensible, customizable, self-documenting real-time display editor."
The Emacs sensor requires Emacs 21.1 or later and Java 1.5.0 or later. It must be possible to invoke this version of Java at the command line using 'java'.
Follow the instructions in Chapter 2, Client-side configuration: Tool sensor installation to set your Hackystat host and user key.
In the HackyInstaller main window, select the Emacs sensor and press "Configure Selected Sensor". Figure 26.22, “ Emacs installer configuration window ” shows what the configuration window should look like after the path to Emacs is set, the sensor is enabled, and the "Install" button has been pressed to install the sensor.
This sensor supports the following properties and paths:
Enable Emacs Sensor: This property controls whether the sensor is active or not. If not checked, the sensor will not collect or send data even if installed.
Enable Emacs BuffTrans Sensor: This property controls whether or not buffer transition monitoring is enabled. If checked, then a timer wakes up every five seconds and checks to see whether a new buffer is being visited, and if so, records a BuffTrans sensor data instance.
Enable Emacs DevEvent Sensor: This property controls whether or not DevEvent sensor data collection is enabled. See below for more information on DevEvents.
.emacs directory: This path specifies the directory in which Emacs looks for the .emacs file. The Emacs sensor will automatically insert some emacs lisp code into the .emacs file to load the sensor each time Emacs is invoked.
After restarting Emacs with these changes to your .emacs file, you can begin the process of verifying your installation by visiting the *hackystat-shell* buffer. Figure 26.23, “ *hackystat-shell* buffer on startup ” illustrates what this buffer will look like in Emacs when the sensor starts up correctly.
This indicates that the SensorShell started up correctly and some initialization commands to set the tooltype and to add a "Tool Startup" activity succeeded. Note that these initial commands may appear out of order in the buffer due to startup delays, but that does not lead to an error.Â
If everything looks good in the *hackystat-shell* buffer, then you should edit one or more files for a few minutes, then exit Emacs (which will trigger a send of the data to the server). Then login to your account on the Hackystat server, and use the "List Sensor Data" command on the Extras page to verify that Activity data for today's date was received by the server for the "Emacs" tool, as illustrated in Figure 26.24, “ List Sensor Data with Emacs data ”.
If the List Sensor Data command verifies that you are receiving data at the server, then the final check is to use the Daily Diary command to verify that state change events are being sent and abstracted into the Most Active File, as illustrated in Figure 26.25, “ Daily Diary with Emacs data ”.
Once you have successfully edited a file, verified that it was sent to the server, and found it listed as the Most Active File in the Daily Diary, you can feel confident that the Emacs sensor was installed correctly.
The first step in troubleshooting your sensor installation is to verify that your Hackystat host and key settings are valid and that you can contact the Hackystat server, as described in Section 2.4, “HackyInstaller GUI: Setting and verifying the Hackystat host and user key”
If an error occurs during Emacs startup that results in the sensor.properties file being displayed in the active buffer, this may be due to line ending problems with the sensor.properties file. Make sure that this file is in the correct format for your operating system. In Unix, the dos2unix command can fix line endings.
The Emacs sensor writes out a file called emacs.0.log to the .hackystat/logs directory that can be useful in debugging your installation. It is actually a persistent version of the *hackystat-shell* buffer. Under normal conditions, this file should look similar to Figure 26.26, “ Log file for Emacs sensor ”.
If none of the above troubleshooting activities solves your problem, then you should send an email to your Hackystat Administrator to request help. Please include in your email the following information:
The output from 'java -version'.
The output from 'emacs -version'.
The output from 'java -jar sensorshell.jar -verify'.
The contents of your sensor.properties file.
The contents of the emacs.0.log file.
A description of the problem you are having.