Tracing data from check-out operations

This topic describes how to use the Trace utility to track check-out operations.

Using the check-out Trace utility

The StarTeam check-out Trace utility generates a *.csv file that provides data about check-out operations for the server configuration for which tracing is enabled. Before you run the utility, you must enable tracing for the server configuration in the starteam-server-configs.xml file. With tracing enabled, the server generates a trace record for each checked out file and saves the information in a trace file (check-out.cotrc). The utility uses the trace file as input and outputs a *.csv file containing data about the check-out operations. You can import the output from the *.csv file into Datamart or an Excel spreadsheet.

The *.csv file contains the following information for each check-out:

Note: Checkout data will not be included in the generated .cotrc file if a Cache Agent performed the checkout. Data will only be included in the .cotrc file if the check-out operation was performed by the Server.

  • user ID
  • user name
  • time stamp (date/time of check-out)
  • project ID
  • project
  • view
  • view ID
  • folder ID
  • folder path
  • file ID
  • filename
  • file revision number

Note: To optimize performance, StarTeam does not immediately update trace files. StarTeam buffers the information for the trace file in memory and writes it to the trace file during idle time processing.

You can find the check-out Trace utility in the StarTeam Server root installation folder (CheckoutTraceDump.exe). For information about using the utility, refer to the links at the bottom of this topic.

Back to top

Enabling tracing for server configurations

When you enable tracing for a server configuration, the server saves a trace record for each file that is checked out in a trace file (check-out.cotrc). You then use the trace file as input for the Check-out Trace utility to generate a *.csv file containing information about check-out operations.

This section describes how to manually enable the tracing.

To manually enable tracing for a server configuration

  1. Open the starteam-server-configs.xml file. You can locate the file under the StarTeam Server root installation folder.
  2. Update the following elements with a value of “1” for each server configuration that you wish to enable tracing on:

    <option name=”FileAllowCheckoutTrace” value=”1”/>

    <option name=”FileEnableCheckoutTrace” value=”1”/>

    The first option activates the tracing code. While the second option turns tracing on or off. A value of “1” represents true or on. A value of “0” represents false or off. To enable tracing, both values must be “1”.

  3. Save the changes to starteam-server-configs.xml.
  4. Shut down and restart the server configuration so that it can detect changes from starteam-server-configs.xml.

Note: To enable tracing using the Server Administration Tool, refer to Activating Diagnostic Tests.

When you set both options in starteam-server-configs.xml to “1”, the server configuration creates Checkout.cotrc files in the Trace folder (a subfolder of the repository folder Checkout.cotrc). When the size of the current trace file reaches 128 MB, the server saves the current trace file and creates a new trace file. The name of the older trace file becomes the name plus a time-stamp, similar to the time-stamp naming convention found in StarTeam server.log files. When you shutdown the server configuration, the server saves the trace file with a time-stamp appended to the filename. When you restart the server configuration, the server creates a new trace file.

Note: To optimize performance, StarTeam does not immediately update trace files. StarTeam buffers the information for the trace file in memory and writes it to the trace file during idle time processing.

Back to top

Generating .CSV files for check-out operations

Before you run the utility, you must enable tracing for the server configuration. With tracing enabled, the server generates a trace record for each checked out file and saves the information in a trace file (Checkout.cotrc). The utility uses the trace file as input and outputs a *.csv file containing data about the check-out operations.

The Check-out Trace utility takes one or more check-out trace (*.cotrc) files as input and outputs one *.csv text file containing check-out trace data as comma-delimited values. The default filename for the .csv file is identical to the name of the trace file with the extension .csv. For example, when the trace filename is Checkout.cotrc, then the csv output filename is Checkout.cotrc.csv.

To run the Check-out Trace utility

  1. At the command prompt, navigate to the CheckoutTraceDump.exe file in the StarTeam Server root installation folder.
  2. The -go option signals the utility to run with default options. You can set many parameters for the utility. For a list of all of the available options, review the command line operations for the utility at the link referenced at the bottom of this topic.

    Note: By default, the server saves the trace files in the Trace folder (a subfolder of the repository folder Checkout.cotrc). You cannot run the utility against the current trace file, but you can copy the trace file and run the utility against the copy.

Tip: If you want to run the utility from a workstation rather than on the server, you can copy CheckoutTraceDump.exe and OSSup.dll to the alternate location. Be cautious not to move OSSup.dll to the new location because the server configuration also relies on it. Additionally, the utility depends on the Microsoft .NET Runtime, so it must be available on the alternate workstation.

Back to top