The Unix CLI sensor records Unix shell command invocations and the machine name where they were invoked and sends this data to the Hackystat server when the user logs out. It is implemented using a timestamped "history" mechanism provided by most Unix shell environments.
![[Note]](gfx/admonitions/note.gif) | No path attribute in this sensor |
|---|---|
Unfortunately, the Unix CLI sensor does not at present determine the 'path' attribute associated with the CLI sensor data, and so sends a default value of "unknown". This severely compromises the utility of this sensor, since the data cannot currently be associated with a Project using the normal Workspace association mechanisms. We recommend you use the ShellLogger package instead along with the ShellLogger sensor. | |
Analyzing command line invocation sequences can potentially provide useful insight into software development processes in certain environments, such as high performance computing, where command line tool invocation forms a central part of development.
The Unix CLI sensor is implemented by adding a script (specified below) to your .logout file, which collects together the command line data from your session and sends it off to the Hackystat server.
The Unix CLI sensor records data using the CLI sensor data type, documented in Section 25.5, “CLI”
The CLI sensor requires Java 1.5.0 or later and Unix shells sh, csh, or tcsh. Bash is also supported, but only for versions 3.0 and above, as earlier versions do not support history timestamps.
First, make sure that history is enabled in your shell. You can check by typing 'history' and seeing if your previous commands are displayed. In csh, for example, history is not enabled until you set the "history" environment variable to an integer value. You can set the variable in your .cshrc as follows:
set history = 1000
Second, make sure that the -S option to history is supported and generates a file containing alternating lines of timestamp and command data. You can check this by executing the following command:
bertha:~ > history -S history.test
Third, verify that the history file contains timestamps by checking to see if the file contains alternating lines of timestamps and their associated command line invocations. To verify this, display the test file you just created, and check to see that it follows the following format:
bertha:~ > cat history.test #+1102018906 more .logout #+1102018909 ls #+1102019241 history -S history.test
If your Unix system does not contain the history program, or if history -S does not generate a file, or if the file generated does not generated timestamped data in the format specified above, then this sensor will not work in your environment without modifications.
First, set the bash history size with the "HISTSIZE" environment variable. This variable should be set to an integer value. You can set the variable in your .bashrc as follows:
HISTSIZE=1000 export HISTSIZE
Finally, make sure that the history command is capable of outputting entries with a timestamp. Only bash versions 3.0 and greater are capable of this feature. You can check this by executing the following command (ensure that the version is greater than 3.0):
bash --version
If your version is greater than 3.0, then you can set the bash history time format with the "HISTTIMEFORMAT" environment variable. This variable should be set to "%s", which stands for seconds after the epoch. You can set this variable in your .bashrc as follows (or HackyInstaller will append this automatically to your .bash_logout file):
HISTTIMEFORMAT=%s export HISTTIMEFORMAT
Following this step, you will notice a UTC timestamp appearing in your history log before the command, in place of the numerical ordering of the command.
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 Unix CLI sensor and press "Configure Selected Sensor". Figure 26.10, “ Unix CLI installer configuration window ” shows what the configuration window should look like after the sensor is enabled, and the "Install" button has been pressed to install the sensor.
This sensor supports the following properties and paths:
Enable CLI 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.
To verify your CLI sensor installation, simply type a few commands into your shell and then exit the shell, which should invoke the .logout script. Alternatively, you can 'source' the .logout file to invoke the script without exiting. Figure 26.11, “ CLI logout ” shows the shell output from an example logout.
Once you verify that the logout script was invoked, login to your account on your Hackystat server, and use the "List Sensor Data" command on the Extras page to verify that CLI data for today's date was received by the server for the CLI tool, as illustrated in Figure 26.12, “ List Sensor Data with CLI data ”.
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”
The CLI sensor writes out a file called cli.0.log to the .hackystat/logs directory that can be useful in debugging your installation. Under normal conditions, this file should look similar to Example 26.15, “Log file for CLI sensor”.
Example 26.15. Log file for CLI sensor
Hackystat Version: 6.3.1124 (November 24 2004 12:05:38)
SensorShell started at: 12/02/2004 10:21:52
Type 'help' for a list of commands.
Host: http://hackystat.ics.hawaii.edu/ is available and key is valid.
Defined shell command: Cli
Defined shell command: Activity
Defined shell command: Dependency
Defined shell command: ReviewActivity
Defined shell command: Coverage
Defined shell command: Issue
Defined shell command: UnitTest
Defined shell command: Commit
Defined shell command: BuffTrans
Defined shell command: Perf
Defined shell command: Build
Defined shell command: FileMetric
Defined shell command: ReviewIssue
#> AutoSend [1]
AutoSend OK (set to 1 minutes)
AutoSend enabled every 1 minutes.
Checking for offline data to recover.
No offline data found.
#> Cli [setTool, Cli]
setTool OK
#> Cli [add, bertha, su, ]
Cli add OK (1 total)
#> Cli [add, bertha, more, .logout]
Cli add OK (2 total)
#> Cli [add, bertha, ls, ]
Cli add OK (3 total)
#> Cli [add, bertha, logout, ]
Cli add OK (4 total)
#> Cli [add, bertha, more, .logout]
Cli add OK (5 total)
#> Cli [add, bertha, ls, ]
Cli add OK (6 total)
#> Cli [add, bertha, logout, ]
Cli add OK (7 total)
#> send
Sending sensor data (12/02 10:21:54)
Activity: Send OK (No entries to send.)
Cli: Send OK (7 entries)
Dependency: Send OK (No entries to send.)
Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
ReviewActivity: Send OK (No entries to send.)
Coverage: Send OK (No entries to send.)
AutoSend: AutoSend OK ('send' command ignored)
Issue: Send OK (No entries to send.)
BuffTrans: Send OK (No entries to send.)
Commit: Send OK (No entries to send.)
UnitTest: Send OK (No entries to send.)
Build: Send OK (No entries to send.)
Perf: Send OK (No entries to send.)
FileMetric: Send OK (No entries to send.)
ReviewIssue: Send OK (No entries to send.)
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 'java -jar sensorshell.jar -verify'.
The contents of your sensor.properties file.
The contents of the cli.0.log file.
A description of the problem you are having.