[Next] [Previous] [Top] [Contents] [Index]

RootCause

RootCause Command Reference

The following commands are available from the command line after RootCause has been installed(see Chapter 4, "Getting Started").

rootcause

The rootcause command is designed to run in a simple, intuitive manner when default file names are used. When run with no arguments, it gives version and license information. When run with rootcause -h, it shows the following commands, which are described in detail in this chapter.

rootcause build
build traces/probes in workspace.

rootcause collect
collect agent workspace data for analysis.

rootcause config
show current configuration information.

rootcause decollect
unpack collected workspace data for analysis.

rootcause deploy
package a workspace for remote deployment.

rootcause format
format data in workspace.

rootcause log
perform operations on rootcause log file.

rootcause merge
merge two workspaces to create a third.

rootcause new
create a new workspace.

rootcause off
disable rootcause intercept of applications.

rootcause on
enable rootcause intercept of applications.

rootcause open
start the RootCause GUI.

rootcause register
register an application with a workspace.

rootcause run
run any command under rootcause.

rootcause status
show if rootcause is enabled.

rootcause xrun
run a command under rootcause in a separate window.

rootcause build

The rootcause build command updates a RootCause workspace without opening the GUI. This is useful for maintaining workspaces as part of a script-driven product development process. The location of a workspace is provided, along with paths to all relevant programs and modules whose locations or contents may have changed. Note that a side-effect of this process may be to lose traces that no longer apply to a changed module.

Syntax:

rootcause build 
  [-Fh] [ -x program_file | file.class | file.jar ]
  [-m module]*
  [-w] workspace.aws

Options:

-F
force the build even if the workspace is locked.

-h
give this command's usage

-x program_file

the executable program, or the .class or .jar file containing your Java application's main entry. This is the same as the argument to Reset Program in the GUI.

-m module
the path of a dynamic module that the program applies to. This is the same as the argument to Reset Dynamic Module in the GUI.

-w workspace.aws

an existing RootCause workspace.

Examples:

  1. Rebuild workspace Pi.aws against current modules in case they've changed:

    rootcause build Pi.aws

  2. Update the RootCause self-analysis workspace for the current installation location:

    rootcause build -x %APROBE%\lib\probeit.jar
    -m %APROBE%\lib\libdebugInfo.dll
    -w %APROBE%\arca.aws

rootcause collect

The rootcause collect command is executed on a remote computer where the RootCause Agent component has been installed to gather the RootCause data together into a single .clct file to be transmitted to a computer where the RootCause GUI component has been installed for subsequent decollection and analysis. It examines the rootcause registry to determine the workspace for the classes, if no workspace is specified. Multiple classes and workspaces may be specified for collection. If no arguments are supplied, the RootCause log and registry are collected.

Syntax:

rootcause collect 
  [-AFh] [ -o clct_file ] [ -f other_file ]
  [ [-x]  program_file | -c class | [-w] workspace.aws ]...

Options:

-A
suppress generation and collection of for native modules. This might be done to reduce the download size if you are sure the local and remote modules are identical.

-F
force overwriting of clct_file, if present.

-h
give this command's usage

-o clct_file
the collect file to create (default: first_argument.clct)

-f other_file
any other file (not directory) to be added to the clct_file. You can also simply copy files or directories into the workspace.

-x program_file

the registered program to which deployed workspace applies

-c class
the registered Java class to which deployed workspace applies

-w workspace

the workspace contents to be collected if program or class is not known

Examples:

  1. The following command collects the data for the Java class Pi and the workspace fred.aws and places those two RootCause traces into the single file myserver.clct.

    rootcause collect -c Pi -w fred.aws -o myserver.clct

rootcause config

The rootcause config command reports current configuration information. With no arguments it shows the installation directory and license information.

Syntax:

rootcause config [ -dhlLnRuvV ]

Options:

-d
give installation directory (that is, the value of %APROBE%)

-h
give this command's usage

-l
give license information

-L
give application log path (%APROBE_LOG% or default location).

-n
give product name (Console or Agent).

-R
give application log path (%APROBE_REGISTRY% or default location).

-u
give user directory (%APROBE_HOME% or default).

-v
give product version number.

-V
give product version description (default).

Examples:

  1. Show the current installation information:

    C:\> rootcause config
    RootCause Console 2.1.4 (030405)
    Installed in C:\RootCause
    This product is licensed to 1111 OC Systems, Inc.
    This license will expire on 31-dec-2006.

rootcause decollect

The rootcause decollect command unpackas a .clct file built by the rootcause collect command. This function is also performed by the Decollect operation in the RootCause GUI (see "Decollect Data Dialog").

The result of this operation is a directory tree whose root directory has suffix .dclct.

Syntax:

rootcause decollect [-F] [-o directory] clct_file

Options:

-F
force delete of directory, if present

-o directory
extract into directory (default: clct_file_name.dclct)

clct_file
collect file that was built by rootcause collect

Examples:

  1. Decollect the data in myserver.clct into myserver.dclct

    rootcause decollect myserver.clct

rootcause deploy

The rootcause deploy command packages a workspace for use in a remote (agent) environment. This function is also performed by the Deploy operation in the RootCause GUI (see "Deploy Dialog"). The result of this operation is a zip file with suffix .dply. Note that this command does not verify the workspace is already built. If you're not sure, do rootcause build first.

Syntax:

rootcause deploy 
  [-Fh][ [-x] program_file | [-c class] [-w]workspace.aws ]
  [-l license_file] [-m module][-o dply_file]

Options:

-c class
the Java class registered with the workspace you wish to deploy.

-F
force overwriting of dply_file, if present.

-h
give this command's usage

-l license_file

the agent license file to include in the deployed workspace (default %APROBE%\licenses\agent_license.dat.

-m module
is a module (DLL) for which an ADI file should be generated.

-o dply_file
the deploy file to create (default: workspace.clct)

-x program_file

the program registered with the workspace you wish to deploy.

-w workspace.aws

an existing, built RootCause workspace.

Examples:

  1. Deploy workspace Pi.aws.

    rootcause deploy Pi.aws.

  2. Deploy workspace forclass Factor and module Factor.dll into Factor.dply.

    rootcause deploy -c Factor -m \Programs\Factor.dll -o Factor.dply

rootcause format

The rootcause format command runs apformat on the data collected in the specified workspace. This produces output similar to that produced by Save As Text in the RootCause GUI. By default rootcause format operates on the most current process. Because it formats all the data it can take a while for large amounts of data. You can use the -O option in conjunction with the apformat "-n" option to limit it to specific APD files, as shown in Example 3 below.

Syntax:

rootcause format 
  [-hlr][-p PID][-O "options"][-t tmpdir]
  [-w] workspace.aws

Options:

-h
give this command's usage

-l
list the APD rings (Process Data Sets) in the workspace, but don't format anything. The newest data set is listed first.

-r
raw: just run apformat directly on the APD file (with options specified using -O) rather than using the workspace's formatting script.

-p PID
format data for the process given by PID

-O "options"

pass options to the apformat command. The options must be in quotes, and quotes in the options themselves must be preceded by a backslash.

-t tmpdir
specifies the directory where intermediate files are to be produced. These can get very large--up to 10 times the size of the APD files depending on the formatting--and this can be used to avoid disk-space restrictions where the workspace resides.

-w workspace.aws

the RootCause workspace containing the data to be formatted.

Examples:

  1. Format the newest data set in Pi.aws into the file Pi.txt.

    rootcause format Pi.aws > Pi.txt

  2. List the Process Data Set in workspace Pi.aws.

    C:\> rootcause format -l Pi.aws
    C:\Work\Pi.aws\Pi.class.apd.119\Pi.class.apd
    C:\Work\Pi.aws\Pi.class.apd.117\Pi.class.apd

  3. Run apformat directly on the newest data file for process 117 in Pi.aws.

    rootcause format -r -O "-n 0" -p 117Pi.aws

rootcause log

The rootcause log command provides information about the RootCause Log, and allows its maximum size to be changed.

Syntax:

rootcause log [-hlnsFZ | -s size ]

Options:

-F
force -s size or -Z operation without confirmation

-h
give command-line help

-l
list log file contents to standard output

-n
list the log file name to standard output

-s
list the log file size to standard output

-s size
set the maximum size of the log to size bytes (size > 1000)

-Z
clear the contents of the log file

Examples:

  1. Write the contents of the log to standard output:

    rootcause log

  2. Set the size of the log to 20000 bytes:

    rootcause log -s 20000

rootcause merge

The rootcause merge command merges two workspaces to create a new, third workspace. It works by copying the first primary workspace to the third result workspace, then adding compatible traces and UALs from the second secondary workspace. A module must exist in both the primary and secondary workspaces in order that traces for that module appear in the result workspace.

There is no GUI operation equivalent to rootcause merge. You can use it in conjunction with the GUI by:

Note: The rootcause build and rootcause register operations must be applied to the result workspace before the result workspace can be used to trace an application.

Syntax:

rootcause merge [-Fh] primary.aws secondary.aws result.aws

Options:

-F
force result.aws to be overwritten if it exists

-h
give command-line help

primary.aws

The primary workspace, on which the result workspace is based.

secondary.aws

The secondary workspace, from which additional traces and UALS are added to the result workspace.

result.aws
The new workspace that is created.

Examples:

  1. Merge traces in PiDetails.aws into Pi.aws to produce PiPlus.aws and make PiPlus.aws the new workspace for tracing Pi.

    rootcause merge PiDetails.aws Pi.aws PiPlus.aws
    rootcause build -w PiPlus.aws
    rootcause register -c Pi -w PiPlus.aws

rootcause new

The rootcause new command creates a new workspace. Generally this is done through the RootCause GUI using the New menu item or Open Associated Workspace; (see "New Workspace Dialog"). The result of this operation is the named workspace, initialized to do default tracing. If the -r option is used, the workspace is also registered with the specified program or Java class.

Syntax:

rootcause new
  [-Fhr][-c class] -x program_file  [-w]workspace.aws ]

Options:

-c class
the Java class registered with the workspace you wish to deploy.

-F
force overwriting of workspace.aws if it exists.

-h
give this command's usage

-r
register the new workspace with the specified program or Java class

-x program_file

the executable program or Java .class or .jar file the workspace will be used to trace (as on the rootcause open command).

-w workspace.aws

the new workspace to be created.

Examples:

  1. Create and register a new workspace for Pi.class.

    rootcause new -r -x Pi.class -c Pi -w Pi.aws.

rootcause off

Use the rootcause off command to disable rootcause interception of processes on your machine.

Syntax:

rootcause off

rootcause on

Use the rootcause on command to start the inspection and interception of processes on your machine to determine if they should be traced with rootcause.

Syntax:

rootcause on [ verbose | quiet ]

Options:

If verbose is specified , every process is recorded in the rootcause log. If quiet is specified, only applications trace with rootcause are recorded in the log. If no qualifier is given, the logging level is not changed. The initial value after installation is verbose, so that "rootcause on" will result in all processes being logged.

rootcause open

The rootcause open command starts the RootCause GUI. If the application class specified on the command line is registered, the GUI will automatically set the workspace from the registry entry for the application. If the application is not registered, the GUI will prompt for a new workspace name and register the application. If no arguments are specified, the current RootCause Log file is opened.

Syntax:

rootcause open 
  [[-x] program_file]
  [-c classname] [[-w] workspace.aws]
  [ [-d] dir.dclct | [-z] file.clct ]

Options:

program_file
the executable program file, or the the .class or .jar file containing your Java application's main entry

classname
the main class name. This is required if classname is not the same as file

workspace.aws

a new or existing RootCause workspace

dir.dclct
a directory created by the RootCause Decollect operation

file.clct
a file created by the rootcause collect command

Examples:

  1. Start the RootCause GUI and examine the RootCause Log file in a Trace Display window.

    rootcause open

  2. Start the RootCause GUI to open new or existing workspace converter.aws.

    rootcause open converter.aws

  3. Start the RootCause GUI to open a new or existing workspace for main class Pi compiled into file Pi.class.

    rootcause open Pi.class

  4. Start the RootCause GUI to open a new or existing workspace for main class com.ocsystems.probeit.Main compiled into file probeit.jar.

    rootcause open probeit.jar -c com.ocsystems.probeit.Main

  5. Start the RootCause GUI to unpack (decollect) the collected rootcause data in pi_demo.clct.

    rootcause open pi_demo.clct

rootcause register

The rootcause register command provides the interface to the RootCause registry. The GUI will allow you to add or delete the current workspace from the registry, but you must use the register command to otherwise manipulate the registry. It is likely that, over time, more GUI support will be added to manipulate the registry, but on computers where only the RootCause Agent is installed, there is no GUI and the register command must be used.

Syntax:

rootcause register [subcommand ] options  [deploy_file]

Description:

subcommand

The subcommand flag designates the operation to be performed:

-a
add a new entry in the registry (default)

-d
delete an entry from the registry

-h
give command help

-k
return 0 iff specified args are already registered & enabled

-l
lists all registry contents

-lr
list registry name only

-lw
list workspace name only

-lx
list only registered JVM or class only

-s debug
enable/disable debug mode with -e on/off (off by default)

-s verbose
enable/disable verbose mode with -e on/off (on by default)
With verbose mode on, all processes are recorded in the log; with verbose off, only traced applications are recorded.

-Z
clear entire registry contents, including -s settings, returning them to their default values.

options

Options further qualifying the above are:

-c classname
probe Java commands naming main class classname

-e on | off
off specifies 'disabled' (default: on)

-F
force without confirmation

-j dir
dir is root of JRE containing java exe to probe

-m file
file is a module required for deploy_file consistency checking

-r file
file is registry file to use

-w dir.aws
file is workspace to use

-x file
file is executable to probe

deploy_file
is a .dply file to unpack into a registered workspace

Examples:

  1. List the registry name and contents:

    rootcause register -l

  2. Delete the registry entry for class Pi:

    rootcause register -d -c Pi

  3. The following command will do the following all in one step:

    • register the program

    • create the workspace (if it does not exist)

    • deploy the trace into the workspace

      This would be the typical command used on a remote computer where only the RootCause Agent component was installed in order to implement a .dply file generated by the RootCause GUI component. After this command is issued, you would merely execute rootcause on and run the application.

      rootcause register jfrob.dply

rootcause run

Use rootcause run before your command to cause it to be run with rootcause on, independent of the current rootcause status. The command specified will be run in the current window exactly as if it were not preceded by rootcause run. This is equivalent to

rootcause on
command
rootcause off

Syntax:

rootcause run command

Options:

command
any shell command

Example:

  1. Run the Pi application with rootcause on:

rootcause run java -cp %APROBE%\Demo\RootCause\Java Pi

rootcause xrun

Identical to rootcause run, but the command is run in a separate window. This is used by the Run button in the RootCause GUI.

Syntax:

rootcause xrun command

rootcause status

Use the rootcause status command to show whether rootcause tracing is currently enabled or disabled.

Syntax:

rootcause status

[Next] [Previous] [Top] [Contents] [Index]

Copyright 2006 OC Systems, Inc.