Difference between revisions of "RCUG RootCause Command Reference"
m |
m |
||
Line 35: | Line 35: | ||
<DT>'''<A HREF="#MARKER-9-2101">rootcause open</A>'''<DD> start the RootCause GUI. | <DT>'''<A HREF="#MARKER-9-2101">rootcause open</A>'''<DD> start the RootCause GUI. | ||
<DT>'''<A HREF="#MARKER-9-2107">rootcause register</A>'''<DD> register an application with a workspace. | <DT>'''<A HREF="#MARKER-9-2107">rootcause register</A>'''<DD> register an application with a workspace. | ||
+ | <DIV ID=MARKER-9-2119></DIV> | ||
<DT>'''<A HREF="#MARKER-9-2119">rootcause run</A>'''<DD> run any command under rootcause. | <DT>'''<A HREF="#MARKER-9-2119">rootcause run</A>'''<DD> run any command under rootcause. | ||
<DT>'''<A HREF="#MARKER-9-2129">rootcause status</A>'''<DD> show if rootcause is enabled. | <DT>'''<A HREF="#MARKER-9-2129">rootcause status</A>'''<DD> show if rootcause is enabled. |
Revision as of 03:12, 4 November 2017
Contents
- 1 RootCause Command Reference
- 1.1 <A NAME=MARKER-9-2009></A>RootCause and Different Shells
- 1.2 rootcause
- 1.3 <A NAME=MARKER-9-2022></A>rootcause build
- 1.4 <A NAME=MARKER-9-2027></A>rootcause collect
- 1.5 <A NAME=MARKER-10-2038></A><A NAME=MARKER-9-2039></A>rootcause config
- 1.6 <A NAME=MARKER-9-2051></A>rootcause decollect
- 1.7 <A NAME=MARKER-9-2053></A>rootcause deploy
- 1.8 <A NAME=MARKER-9-2063></A>rootcause format
- 1.9 <A NAME=MARKER-9-2075></A>rootcause log
- 1.10 <A NAME=MARKER-9-2079></A>rootcause merge
- 1.11 <A NAME=MARKER-10-2083></A><A NAME=MARKER-9-2084></A>rootcause new
- 1.12 rootcause_off
- 1.13 <A NAME=MARKER-9-2089></A>rootcause_<A NAME=MARKER-10-2090></A>off
- 1.14 rootcause_on
- 1.15 <A NAME=MARKER-9-2094></A>rootcause_<A NAME=MARKER-10-2095></A>on
- 1.16 <A NAME=MARKER-10-2100></A><A NAME=MARKER-9-2101></A>rootcause open
- 1.17 <A NAME=MARKER-9-2107></A>rootcause register
- 1.18 <A NAME=MARKER-9-2119></A>rootcause run
- 1.19 <A NAME=MARKER-10-2126></A><A NAME=MARKER-9-2127></A>rootcause xrun
- 1.20 <A NAME=MARKER-9-2129></A>rootcause status
RootCause Command Reference
The following commands are available from the command line after RootCause has been installed and the setup script in the RootCause installation directory has been executed (see <A HREF="rcc-7.html#MARKER-9-508">Chapter 4, "Getting Started"</A>). <A NAME=HEADING12-2></A><A NAME="UID-09command_rc.fm-998723"></A>
<A NAME=MARKER-9-2009></A>RootCause and Different Shells
Different shells on Solaris have different capabilities. The following differences apply to the different shells:<A NAME=MARKER-2-2010></A>sh (<A NAME=MARKER-2-2011></A>Bourne shell):
The<A NAME=MARKER-2-2012></A>rootcause_on
and <A NAME=MARKER-2-2013></A>rootcause_off
commands are not available. Instead, you must use the dot commands:. <A NAME=MARKER-2-2014></A>rootcause_enable . <A NAME=MARKER-2-2015></A>rootcause_disable
<A NAME=MARKER-2-2016></A>ksh (Korn shell)
You may userootcause on
and rootcause off
instead of rootcause_on
, and rootcause_off
, because rootcause is defined as a shell function. Note that RootCause requires that ksh
be installed, though you need not use it as your shell. On Linux you may have to install pdksh
.<A NAME=MARKER-2-2017></A>csh (C shell)
rootcause_on and rootcause_off are aliases defined in your shell when you "source" setup.csh. C shell does not support shell functions, so "rootcause on" and "rootcause off" won't work.<A NAME=MARKER-2-2018></A>bash
The setup script and shell functions forksh
work for bash
as well. However, ksh is still needed for <A NAME=MARKER-2-2019></A>install_rootcause, <A NAME=MARKER-2-2020></A>rootcause_status, and other scripts.<A NAME=HEADING12-14></A><A NAME="UID-09command_rc.fm-976940"></A>rootcause
The <A NAME=MARKER-2-2021></A>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.- <A HREF="#MARKER-9-2022">rootcause build</A>
- build traces/probes in workspace.
- <A HREF="#MARKER-9-2027">rootcause collect</A>
- collect agent workspace data for analysis.
- <A HREF="#MARKER-9-2039">rootcause config</A>
- show current configuration information.
- <A HREF="#MARKER-9-2051">rootcause decollect</A>
- unpack collected workspace data for analysis.
- <A HREF="#MARKER-9-2053">rootcause deploy</A>
- package a workspace for remote deployment.
- <A HREF="#MARKER-9-2063">rootcause format</A>
- format data in workspace.
- <A HREF="#MARKER-9-2075">rootcause log</A>
- perform operations on rootcause log file.
- <A HREF="#MARKER-9-2079">rootcause merge</A>
- merge two workspaces to create a third.
- <A HREF="#MARKER-9-2084">rootcause new</A>
- create a new workspace.
- <A HREF="#MARKER-9-2089">rootcause_off</A>
- disable rootcause intercept of applications.
- <A HREF="#MARKER-9-2094">rootcause_on</A>
- enable rootcause intercept of applications.
- <A HREF="#MARKER-9-2101">rootcause open</A>
- start the RootCause GUI.
- <A HREF="#MARKER-9-2107">rootcause register</A>
- register an application with a workspace.
- <A HREF="#MARKER-9-2119">rootcause run</A>
- run any command under rootcause.
- <A HREF="#MARKER-9-2129">rootcause status</A>
- show if rootcause is enabled.
- <A HREF="#MARKER-9-2127">rootcause xrun</A>
- run a command under rootcause in a separate window.
<A NAME=MARKER-9-2022></A>rootcause build
The<A NAME=MARKER-2-2023></A>rootcause <A NAME=MARKER-2-2024></A>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'''<EM>program_file</EM> | <EM>file</EM>.class | <EM>file</EM>.jar ] ['''-m'''<EM>module</EM>]* ['''-w'''] <EM>workspace</EM>.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 <A HREF="rcc-11.html#MARKER-9-1376">Reset Program</A> in the GUI. - '-m module'
- the path of a <A HREF="rcc-6.html#MARKER-9-416">dynamic module</A> that the program applies to. This is the same as the argument to <A HREF="rcc-11.html#MARKER-9-1386">Reset Dynamic Module</A> in the GUI.
- '-w workspace'.aws
- an existing RootCause workspace.
Examples:
-
Rebuild workspace pi_demo.aws<A NAME=MARKER-10-2025></A> against current modules in case they've changed: rootcause build Pi.aws
- Update the RootCause self-analysis workspace for the current installation location:<A NAME=MARKER-10-2026></A>rootcause build -x $APROBE/lib/probeit.jar -m $APROBE/lib/libdebugInfo.so -w $APROBE/arca.aws
<A NAME=MARKER-9-2027></A>rootcause collect
The<A NAME=MARKER-2-2028></A>rootcause <A NAME=MARKER-2-2029></A>collect
command is executed on a <A NAME=MARKER-2-2030></A>remote computer where the <A NAME=MARKER-2-2031></A>RootCause Agent component has been installed to gather the RootCause data together into a single <A NAME=MARKER-2-2032></A>.clct
file to be transmitted to a computer where the RootCause GUI component has been installed for subsequent <A NAME=MARKER-2-2033></A>decollection and analysis. It examines the rootcause registry to determine the workspace for the applications<A NAME=MARKER-10-2034></A>, if no workspace is specified. Multiple applications<A NAME=MARKER-10-2035></A> and workspaces may be specified for collection. If no arguments are supplied, the <A NAME=MARKER-2-2036></A>RootCause log and <A NAME=MARKER-2-2037></A>registry are collected.Syntax:
rootcause collect [-'''AFh'''] [ '''-o'''<EM>clct_file</EM> ] [ '''-f''' other_file ] [ ['''-x'''] <EM>program_file</EM> | '''-c'''<EM>class</EM> | ['''-w'''] <EM>workspace</EM>.aws ]...
Options:
- '-A'
- suppress generation and collection of <A HREF="rcc-6.html#MARKER-9-389">ADI file</A>s 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:
-
Collect the data logged in the workspace registered with program converter.exe and the workspace fred.aws, and places those two traces in the single file myserver.clct. rootcause collect -x converter.exe -w fred.aws
-o myserver.clct
<A NAME=MARKER-10-2038></A><A NAME=MARKER-9-2039></A>rootcause config
The <A NAME=MARKER-2-2040></A>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 $<A NAME=MARKER-10-2041></A><A HREF="rcc-10.html#MARKER-9-979">APROBE</A><A NAME=MARKER-10-2042></A>)
- '-h'
- give this command's usage
- '-l'
- give license information
- '-L'
- give application log path ($<A NAME=MARKER-10-2043></A>APROBE_LOG<A NAME=MARKER-10-2044></A> or default location).
- '-n'
- give product name (Console or Agent).
- '-R'
- give application log path ($<A NAME=MARKER-10-2045></A>APROBE_REGISTRY<A NAME=MARKER-10-2046></A> or default location).
- '-u'
- give user directory ($<A NAME=MARKER-10-2047></A><A HREF="rcc-10.html#MARKER-9-982">APROBE_HOME</A><A NAME=MARKER-10-2048></A> or default).
- '-v'
- give product version number.
- '-V'
- give product version description (default).
Examples:
-
Show the current installation information: $<A NAME=MARKER-10-2049></A> rootcause config RootCause Console 2.0.5 (030405) Installed in /app1/product/aprobe <A NAME=MARKER-10-2050></A>This product is licensed to 1111 OC Systems, Inc. This license will expire on 31-dec-2006.
<A NAME=MARKER-9-2051></A>rootcause decollect
The <A NAME=MARKER-2-2052></A>rootcause decollect command unpackas a .clct file built by the <A HREF="#MARKER-9-2027">rootcause collect</A> command. This function is also performed by the <A HREF="rcc-11.html#MARKER-9-1430">Decollect</A> operation in the RootCause GUI (see <A HREF="rcc-11.html#MARKER-9-1528">"Decollect Data Dialog"</A>).The result of this operation is a directory tree whose root directory has suffix .dclct.
Syntax:
rootcause decollect ['''-F'''] ['''-o'''<EM>directory</EM>] <EM>clct_file</EM>
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 <A HREF="#MARKER-9-2027">rootcause collect</A>
Examples:
-
Decollect the data in
myserver.clct
intomyserver.dclct
rootcause decollect myserver.clct
<A NAME=MARKER-9-2053></A>rootcause deploy
The <A NAME=MARKER-2-2054></A>rootcause deploy command packages a <A HREF="rcc-6.html#MARKER-9-482">workspace</A> for use in a <A HREF="rcc-6.html#MARKER-9-456">remote</A> (<A HREF="rcc-6.html#MARKER-9-399">agent</A>) environment. This function is also performed by the <A HREF="rcc-11.html#MARKER-9-1429">Deploy</A> operation in the RootCause GUI (see <A HREF="rcc-11.html#MARKER-9-1520">"Deploy Dialog"</A>). 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 <A HREF="#MARKER-9-2022">rootcause build</A> first.Syntax:
rootcause deploy ['''-Fh'''][ ['''-x'''] <EM>program_file</EM> | ['''-c'''<EM>class</EM>] ['''-w''']<EM>workspace</EM>.aws ] ['''-l'''<EM>license_file</EM>] ['''-m'''<EM>module</EM>]['''-o'''<EM>dply_file</EM>]
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/<A NAME=MARKER-10-2055></A>agent_license.dat
. - '-m module'
- is a <A HREF="rcc-6.html#MARKER-9-440">module</A> (<A NAME=MARKER-10-2056></A><A HREF="rcc-6.html#MARKER-9-461">shared library</A>) for which an <A HREF="rcc-6.html#MARKER-9-389">ADI file</A> 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:
-
Deploy workspace pi_demo.aws<A NAME=MARKER-10-2057></A>. rootcause deploy pi_demo.aws<A NAME=MARKER-10-2058></A>.
- Deploy workspace for factor<A NAME=MARKER-10-2059></A> and module libFactor.so<A NAME=MARKER-10-2060></A> into Factor.dply. rootcause deploy -x /app/bin/factor<A NAME=MARKER-10-2061></A> -m <A NAME=MARKER-10-2062></A> -o Factor.dply
<A NAME=MARKER-9-2063></A>rootcause format
The rootcause format command runs <A HREF="rcc-6.html#MARKER-9-400">apformat</A> on the data collected in the specified workspace. This produces output similar to that produced by <A HREF="rcc-11.html#MARKER-9-1743">Save As Text</A> in the RootCause GUI. By defaultrootcause 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'''<EM>PID</EM>]['''-O''' "<EM>options</EM>"]['''-t'''<EM>tmpdir</EM>] ['''-w'''] <EM>workspace</EM>.aws
Options:
- '-h'
- give this command's usage
- '-l'
- list the <A HREF="rcc-6.html#MARKER-9-393">APD ring</A>s (<A HREF="rcc-6.html#MARKER-9-444">Process Data Set</A>s) 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 <A HREF="rcc-6.html#MARKER-9-443">PID</A>
- '-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.
<A NAME=MARKER-9-2064></A>Examples:
-
Format the newest data set in pi_demo.aws<A NAME=MARKER-10-2065></A> the file
pi_demo<A NAME=MARKER-10-2066></A>.txt
. rootcause formatpi_demo.aws<A NAME=MARKER-10-2067></A> > pi_demo<A NAME=MARKER-10-2068></A>.txt
-
List the <A HREF="rcc-6.html#MARKER-9-444">Process Data Set</A> in workspace pi_demo.aws<A NAME=MARKER-10-2069></A>.
$<A NAME=MARKER-10-2070></A> rootcause format -l
pi_demo.aws<A NAME=MARKER-10-2071></A>
/work/pi_demo.aws/pi_demo.apd.11991/pi_demo.apd /work/pi_demo.aws/pi_demo.apd.11785/pi_demo.apd <A NAME=MARKER-10-2072></A> -
Run <A HREF="rcc-6.html#MARKER-9-400">apformat</A> directly on the newest data file for process 11785 in pi_demo.aws<A NAME=MARKER-10-2073></A>.
rootcause format -r -O "-n 0" -p
11785 pi_demo.aws<A NAME=MARKER-10-2074></A>
<A NAME=MARKER-9-2075></A>rootcause log
The<A NAME=MARKER-2-2076></A>rootcause log
command provides information about the RootCause Log, and allows its maximum <A NAME=MARKER-2-2077></A>size to be changed.Syntax:
rootcause log ['''-hlnsFZ''' | '''-s'''<EM>size</EM> ]
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
<A NAME=MARKER-9-2078></A>Examples:
-
Write the contents of the log to standard output: rootcause log
- Set the size of the log to 20000 bytes: rootcause log -s 20000
<A NAME=HEADING12-150></A><A NAME="UID-09command_rc.fm-973824"></A>
<A NAME=MARKER-9-2079></A>rootcause merge
The <A NAME=MARKER-2-2080></A>rootcause merge
command merges two <A HREF="rcc-6.html#MARKER-9-482">workspace</A>s 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 <A HREF="rcc-6.html#MARKER-9-440">module</A> 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:- Using Workspace->Close to close your current workspace
-
Applying
rootcause merge
from the command line - Using Workspace->Open on the result workspace.
Syntax:
rootcause merge ['''-Fh'''] <EM>primary</EM>.aws <EM>secondary</EM>.aws <EM>result</EM>.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:
-
Merge traces in file_ops.aws into pi_demo.aws to produce pi_demo2.aws and make pi_demo2.aws the new workspace for tracing pi_demo<A NAME=MARKER-10-2081></A> rootcause merge file_ops.aws pi_demo.aws pi_demo2.aws rootcause build pi_demo2.aws rootcause register -F -x pi_demo<A NAME=MARKER-10-2082></A> -w pi_demo2.aws
<A NAME=MARKER-10-2083></A><A NAME=MARKER-9-2084></A>rootcause new
The <A NAME=MARKER-2-2085></A>rootcause new command creates a new <A HREF="rcc-6.html#MARKER-9-482">workspace</A>. Generally this is done through the RootCause GUI using the <A HREF="rcc-11.html#MARKER-9-1362">New</A> menu item or <A HREF="rcc-11.html#MARKER-9-1730">Open Associated Workspace</A>; (see <A HREF="rcc-11.html#MARKER-9-1434">"New Workspace Dialog"</A>). 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'''<EM>class</EM>] '''-x'''<EM>program_file</EM> ['''-w''']<EM>workspace</EM>.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 <A HREF="#MARKER-9-2101">rootcause open</A> command). - '-w workspace'.aws
- the new workspace to be created.
Examples:
-
Create and register a new workspace for pi_demo.exe<A NAME=MARKER-10-2086></A>. rootcause new -r -x pi_demo.exe<A NAME=MARKER-10-2087></A> -w pi_demo.aws<A NAME=MARKER-10-2088></A>.
rootcause_off
<A NAME=MARKER-9-2089></A>rootcause_<A NAME=MARKER-10-2090></A>off
Use the<A NAME=MARKER-2-2091></A>rootcause_<A NAME=MARKER-10-2092></A>off
command to disable rootcause interception of processes on your machine.Syntax:
rootcause<CODE>_<A NAME=MARKER-10-2093></A></CODE>off
<A NAME=HEADING12-188></A><A NAME="UID-09command_rc.fm-976801"></A>
rootcause_on
<A NAME=MARKER-9-2094></A>rootcause_<A NAME=MARKER-10-2095></A>on
Use the<A NAME=MARKER-2-2096></A>rootcause_<A NAME=MARKER-10-2097></A>on
command to start the inspection and interception of processes on your machine to determine if they should be traced with rootcause.Syntax:
<CODE>rootcause_<A NAME=MARKER-10-2098></A>on<A NAME=MARKER-10-2099></A></CODE><A NAME=HEADING12-192></A><A NAME="UID-09command_rc.fm-949424"></A>
<A NAME=MARKER-10-2100></A><A NAME=MARKER-9-2101></A>rootcause open
The<A NAME=MARKER-2-2102></A>rootcause <A NAME=MARKER-2-2103></A>open
command starts the <A NAME=MARKER-2-2104></A>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'''] <EM>program_file</EM>] ['''-c'''<EM>classname</EM>] [['''-w'''] <EM>workspace</EM>.aws] [ ['''-d'''] <EM>dir</EM>.dclct | ['''-z'''] <EM>file</EM>.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 <A HREF="rcc-11.html#MARKER-9-1430">Decollect</A> operation
- file.clct
- a file created by the
rootcause collect
command
Examples:
-
Start the RootCause GUI and examine the RootCause Log file in a Trace Display window. rootcause open
- Start the RootCause GUI to open new or existing workspace converter.aws. rootcause open converter.aws
- Start the RootCause GUI to open a new or existing workspace for program converter.exe rootcause open converter.exe
- <A NAME=MARKER-10-2105></A>Start the RootCause GUI to unpack (<A NAME=MARKER-2-2106></A>decollect) the collected rootcause data in pi_demo.clct. rootcause open pi_demo.clct
<A NAME=MARKER-9-2107></A>rootcause register
The<A NAME=MARKER-2-2108></A>rootcause <A NAME=MARKER-2-2109></A>register
command provides the interface to the RootCause <A NAME=MARKER-2-2110></A>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 <A NAME=MARKER-2-2111></A>RootCause Agent is installed, there is no GUI and the register
command must be used.Syntax:
rootcause register [<EM>subcommand</EM> ] <EM>options</EM> [<EM>deploy_file</EM>]
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 program<A NAME=MARKER-10-2112></A> 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:
-
List the registry name and contents: rootcause register -l
-
Delete the registry entry for
driver.exe
: rootcause register -d -x /build/bin/driver - <A NAME=MARKER-10-2113></A>Turn off recording of all processes in the RootCause log: rootcause register -s verbose -e off
-
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; and
- check it's consistency with the modules to be traced This would be the typical command used on a remote computer where only the <A NAME=MARKER-2-2114></A>RootCause Agent component was installed in order to implement a <A NAME=MARKER-2-2115></A>.dply file generated by the RootCause GUI component. After this command is issued, you would merely execute rootcause_on in the context of the shell<A NAME=MARKER-10-2116></A> and run the application. rootcause register -x /opt/frobco/bin/frobit <A NAME=MARKER-10-2117></A> frobit.dply <A NAME=MARKER-10-2118></A>
<A NAME=MARKER-9-2119></A>rootcause run
Use <A NAME=MARKER-2-2120></A>rootcause run
before your command to cause it to be <A HREF="rcc-6.html#MARKER-9-458">run with rootcause on</A>, independent of the current <A HREF="#MARKER-9-2129">rootcause status</A>. 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_<A NAME=MARKER-10-2121></A>
on
command
rootcause_<A NAME=MARKER-10-2122></A>
off
Syntax:
<CODE>rootcause run</CODE><EM>command</EM>
Options:
- command
- any shell command
Example:
-
Run the pi_demo<A NAME=MARKER-10-2123></A> application with rootcause on: rootcause run $APROBE/demo/RootCause/C++/pi_demo
<A NAME=MARKER-10-2124></A><A NAME=MARKER-10-2125></A>
<A NAME=HEADING12-266></A><A NAME="UID-09command_rc.fm-976908"></A><A NAME=MARKER-10-2126></A><A NAME=MARKER-9-2127></A>rootcause xrun
Identical to <A HREF="#MARKER-9-2119">rootcause run</A>, but the command is run in a separate window. This is used by the <A HREF="rcc-11.html#MARKER-9-1428">Run</A> button in the RootCause GUI.Syntax:
<CODE><A NAME=MARKER-2-2128></A>rootcause xrun</CODE><EM>command</EM>
<A NAME=HEADING12-271></A><A NAME="UID-09command_rc.fm-976931"></A>
<A NAME=MARKER-9-2129></A>rootcause status
Use the<A NAME=MARKER-2-2130></A>rootcause status
command to show whether rootcause tracing is currently enabled or disabled.Syntax:
rootcause status<A NAME="LINK-09command_rc.fm-lastpage"></A>
Copyright 2006-2017 OC Systems, Inc.