Using a Perl Debugger with Server Side Triggers

Introduction

This article describes a method to use a perl debugger on trigger scripts without advanced interprocess debugging tools.

Using a perl debugger with a V4.x server side trigger launched by the server is very difficult and encounters two known obstacles:

1. The server will fire the trigger and the debugger will run in a thread of the detached server process; the debugger will start but will probably not communicate with you. However, if you manually started the server via a shell command then the perl debugger will start, accept input from the keyboard, then you will loose contact with the debugger; it does not have exclusive access to the keyboard because it is running in the context of the detached server process. The next command you type will go to the shell, not the debugger.  It gets messy from there.
2. Debugging on your live server means another AccuRev command could launch the same trigger in debug mode and the AccuRev client that issued the command will appear to be “hung” because the server thread for that command has called the debugger.  Also, if you started the server from the shell command, you will now have two debuggers trying to communicate with you. Running two different triggers in debug mode will create madness for you and get your users very upset!

Summary

• Trigger parameter files facilitate communication between the server process and triggers.
• The AccuRev server does not provide a mechanism to preserve trigger parameter files; they are temporary and removed.
• XML is used for most trigger parameter files but some still use flat files. Study the original trigger to know how to process the format.
• Modify the trigger file to capture and preserver the trigger parameter files. There can be many parameter files per transaction. Compose the file name based upon the trigger name, sequence number, and epoch second.
• Practice continuous process improvement! Use a semaphore file to activate and deactivate the feature to capture the parameter data to a file. You will enable the feature for a few minutes to collect samples then disable it.  The semaphore allows you to reuse the feature without editing the trigger script.
• Once you have enabled the facility and have collected a few trigger parameter dump files, choose an interesting one and make a copy; the copy step is important because the trigger you are debugging will reinitialize the trigger parameter file to return data back to the server. NOTE: Some triggers expect both an XML and flat parameter files. Study the trigger to determine the correct calling arguments.
• Use the copy of the parameter file and pass it as a command line parameter to the trigger you run with a Perl debugger.
• You can now single step through your trigger.
• You must make a new copy of the original parameter file before restarting the debugging session because the file you passed into your trigger was reinitialized. You do not need to exit the debugger, just make a new copy of the trigger file before you issue the debugger “R” (restart) command.

Details

I extend AccuRev functionality to support development processes and I create complex triggers that are easier to develop with a Perl debugger; this is especially true when your triggers are manipulating issue tracking data.  The AccuRev CLI manual provides good information about the triggers but you might need subtle details that are beyond the scope of the documentation. Walking through trigger execution with a debugger gives details about the content of the parameter files and what is passed from trigger to trigger.

I am not aware of any special options to allow the AccuRev server to run Perl triggers in debug mode and my attempts to do so create an unworkable environment. Since triggers are driven by parameter files, I’ve added routines to all the triggers to collect their parameter files. Once I have a collection of interesting parameter files I can launch the trigger scripts with my own Perl debugging tool of choice instead of them being launched by the AccuRev server.  I can also inject faulty data via the parameter file for testing.

The AccuRev server creates a temporary parameter file for each trigger it is calling.  The file name will be a relative path to a temporary directory and each filename will be a sequence number. Please note that a trigger can be fired more than once for a transaction. The temporary file name does not indicate the target trigger script; the trigger name and the AccuRev command that fired the script are embedded in the parameter file.

I embrace the concept of continuous improvement so I anticipate trigger debugging will used many times over the years.  I used a semaphore file to enable and disable the parameter dump functionality to eliminate edits to the trigger scripts on the live repository.  I’ve even attached captured parameter files to issue tickets I’ve submitted to AccuRev support.

Capturing Parameter Files

The AccuRev server determines what trigger to launch then creates one or more temporary files in the cache directory of the site slice and passes a relative directory name and file name(s) in the argument list to the trigger. The server process will ensure a unique sequence number when multiple threads launch the same trigger at the same time.

The steps I use are:

1. Set up my environment:
   1. Define the semaphore file name
   2. Define a directory below the accurev root to store the trigger parameter files.
2. Immediately after the trigger has parsed the XML data, call a utility function and pass it the “hook” name and the relative path to the temporary trigger parameter file that was created by the server. The server created file name will be a sequence number.
3. The utility function will look for the semaphore file in the AccuRev root directory and will simply exit when not found. When the semaphore file is found, the function will compose a unique file name based upon
   1. The trigger “hook” name
   2. The  server supplied file name (minus the directory)
   3. The current epoch second
4. The utility function will create the trigger dump directory as needed, create the file name composed in step #3, and write the trigger parameter data to the new file.

Appendix A has an excerpt of my server_admin_trig.pl and trigger utility module. I save off the parameter file immediately after the trigger has digested the XML data.

I strive to write my perl code to be operating system agnostic. I keep my common trigger code in a perl module that resides in the accurev “bin” directory. I like to avoid external environment dependencies so I explicitly state the lib path (in an OS agnostic way) to my trigger utility module.  I do this because the “use” is a compile time directive and is processed before variables are defined.

Debugging the Trigger with the Captured Parameter File

You must make a copy of the captured trigger parameter file before you use it. Triggers re-initialize the parameter file to pass data back to the server so your captured data will be lost.

1. cd $HOME
2. cp $ACCUREV/trigDumpDir/server_admin_trig-0_0-1246634816   test.dat.org

You launch a perl debugger and pass the trigger parameter file into the script as the first command line argument. Debug to your heart’s content.

1. cd $HOME
2. cp $ACCUREV/storage/site_slice/triggers/server_admin_trig.pl    funTime.pl
3. cp test.dat.org test.dat
4. perl -d funTime.pl test.dat

NOTE:  The script will reinitialize the parameter file for output. You must copy “test.dat.org” to “test.dat” before you restart the debugging session.

Appendix A:

Server_admin_trig.pl – You can download this script here

Trig_utils.pm – You can download this script here

Sample of Captured Trigger Data

Below is the trigger parameter file captured from server_admin_trig.pl for a “mkdepot” command.

This is a simple example. The parameter data gets much more interesting when your objective is to mine transaction or issue tracking details.

Capture file name is: /opt/accurev/ar6060/trigDumpDir/server_admin_trig-0_0-1248023869

<triggerInput>
<depot>test10</depot>
<hook>server_admin_trig</hook>
<command>mkdepot</command>
<principal>ar6060</principal>
<ip>127.0.0.1</ip>
</triggerInput>