rtdriver is the client side socket connection. JProf is the server side connection and it listens for client connections by default. rtdriver allows interactive or automated sessions, depending on the options specified when rtdriver is invoked.
Usage:
------
rtdriver {-n name | -a ipaddr | -l} [-p port | -b] [-np]
[-ta] [-i]
[[{-c | -cx} cmd [#sec]] ...]
| | | |
+------------------------+ +---------------------------+
one required optional
Where:
------
***** Target host options *****
-n name Specifies the host name.
-a ipaddr Specifies the host IP address.
-l Specifies that Local machine is host.
-p port Specifies the host port number, in the range 8888 - 8895,
to connect to.
* Default port number is 8888.
-b Causes RTDriver to attempt to connect to all valid ports
(8888 - 8895) that accept a connection, and to broadcast all
commands to all ports to which a connection was established.
This allows simultaneous control of multiple JVMs.
* Default is to connect to single port and to not broadcast
commands.
-np Causes RTDriver to NOT prefix commands sent over the socket
with commas.
* Default is to prefix all commands with a comma before
sending them over the socket. JProf handles commas as
command separators thus allowing multiple commands to be
sent and processed correctly.
***** Automation options *****
-ta Causes command delay values in user commands to be absolute
times from the time RTDriver is invoked.
* If not specified command delay values are relative to the
previous command (if any).
* Option is ignored if no delay values are given.
* -ta option is only allowed with -n, -a, -l, -p and -c.
* The -ta option *MUST* precede any -c/-cx options.
-c cmd [#sec] Send 'cmd' to the host
-cx cmd [#sec] Execute 'cmd'
Automatically send (-c) or execute (-cx) 'cmd' upon connecting
to host.
In description that follows the word "send" is used to mean
either 'send to host' (if the -c option is used) or 'execute'
(if the -cx option is used).
* If command contains blanks then enclose the entire command
in double quotes. For example:
-c "dumpheap type=3"
* Command execution is sequential with commands sent in the
order in which they were entered (left to right).
* There is an implied delay (socket traffic overhead) between
commands. If you *DON'T* want that delay then specify all
the required commands, separated by commas, as one command.
- For example:
-c fgc -c hd
- Is not the same as:
-c fgc,hd
- "-c fgc -c hd" are sent as two commands and there is
a delay (probably very small) between sending them.
- "-c fgc,hd" is sent as one command, which JProf splits
into fgc followed by hd.
* Commands specified with the -cx option are executed using the
system() library function. RTDriver will not continue until
the command completes.
* If a delay value (#sec) is given, the command is sent:
- #sec seconds after connecting to host if -ta is specified.
- #sec seconds from previous command if -ta is not specified.
* If no delay value is given, the command is sent:
- Immediately after connecting to host if -ta is specified.
- Immediately after previous command if -ta is not specified.
* If using absolute time and more than one command specifies the
same delay time, the commands are executed as they appear in
the command line from left to right.
* Delay value is in seconds and must be a decimal number.
* -c/-cx option(s) are only allowed with -n, -a, -l, -p and -ta.
* Interactive command mode is never entered if -c or -cx is
specified.
- If you need to go into interactive mode then invoke
RTDriver again without the -c or -cx options.
-i Causes interactive command mode to be entered *AFTER* the
last user command is sent.
* If not specified RTDriver exits after the last command is
sent.
* -i should be specified before any command (-c/-cx).
* This option is really only needed if, after sending the
given commands, you would like to enter interactive mode
to continue entering commands. If no commands are given
(no -c/-cx) then RTDriver will enter interactive command
mode anyway.
-nopiclient Never enter piClient mode (included for compatibility)
Valid interactive commands (after connecting):
RTDriver commands
-----------------
?|help - Display this help (but you already knew that).
shutdown - Stop data collection, write data to file, terminate
JVM and exit RTDriver.
exit_rtdriver - Close client connection and exit RTDriver.
JVM continues to run. You can achieve the same
result by pressing Ctrl-C or Ctrl-Break.
JProf commands
--------------
start[=#] - Start collection. If '#', start after '#' seconds.
flush - Write data to file. Data collection continues.
reset - Resets data collection. Can restart with 'start'.
end - Turns off all callflow events, waits for all pending
events to complete, does 'flush' and then 'reset'.
fgc - Request immediate garbage collection.
hd - Request 'detailed' heap dump.
hds - Request 'summary' heap dump.
hdf - Request 'detailed' heap dump followed by flush.
ping - No-op command to see if JProf is accepting commands.
JLM commands
------------
jlm|jlmstart - Start JLM collection *WITH* hold time accounting.
jlml|jlmlitestart - Start JLM collection *WITHOUT* hold time accounting.
jreset|jlmreset - Reset JLM.
jstop|jlmstop - Turn off JLM.
jd|jlmdump - Request JLM dump.
jdr|jlmdumpr - Request JLM dump and Reset JLM.
Interactive command notes:
--------------------------
* JVM/RTDriver termination/exit commands.
- Terminate JVM and exit RTDriver:
"shutdown"
- Leave JVM running and exit RTDriver:
"exit_rtdriver" -or- Ctrl-C/Ctrl-Break
- Turn off instrumentation, leave JVM running and exit RTDriver:
"reset", followed by "exit_rtdriver" -or- Ctrl-C/Ctrl-Break
* Any command other than the ones listed above will be sent, as-is,
to the host (JProf or the JVM itself). See the JProf documentation
for other valid commands.
* If you want commands to be executed (by JProf) as close together as
possible then enter the commands separated by comma without blank
space between them. For example:
- fgc,hd
Will cause an FGC followed immediately by an HD.
- fgc,jlmstart
Will cause an FGC followed immediately by a JLMSTART.
Notes:
------
* Either -n, -a or -l must be specified.
* -p and -b are optional and mutually exclusive options.
* If neither -p nor -b is specified RTDriver will attempt to connect to
host on ports 8888 thru 8895, stopping as soon as the first successful
connection is made.
* If -p is specified RTDriver will only attempt to connect to host on
the given port.
* If -b is specified RTDriver will attempt to connect to host on all
valid ports (8888 thru 8895). Commands will be sent (broadcast) to
all ports to which a successful connection was made.
* Interactive command mode is not entered if either -c or -cx is specified.
If you need to enter additional commands then just invoke RTDriver again.
* You can create fairly complex automatic command sequences by using the
-c and/or -cx options.
* Commands specified with the -cx option are executed using the system()
library function. RTDriver will not continue until the command completes.
* Using the wrong commands will not necessarily result in an error message
from RTDriver. However, the wrong command will be sent across the socket
to the server (either the JVM itself or JProf) and results will be
unpredictable.
Examples:
---------
1) rtdriver -l
Connect to local machine and enter interactive command mode.
2) rtdriver -l -b
Connect to local machine on all ports which accept a connection
and enter interactive command mode. Interactive commands are sent
to all connected ports
3) rtdriver -l -c jlmstart 10 -c jlmdump 50 -c jlmdump 10 -c jlmstop
Connect to local machine, wait 10 seconds, send a 'jlmstart' command,
wait 50 seconds, send a 'jlmdump' command, wait 10 seconds, send a
'jlmdump' command followed by a 'jlmstop' command.
**** Invocations 3 and 4 are functionally identical ****
4) rtdriver -l -ta -c jlmstart 10 -c jlmdump 60 -c jlmdump 70 -c jlmstop 70
Connect to local machine, 10 seconds after connecting send a 'jlmstart'
command, 60 seconds after connecting send a 'jlmdump' command, 70
seconds after connecting send another 'jlmdump' command followed by a
'jlmstop' command.
**** Invocations 3 and 4 are functionally identical ****
5) rtdriver -l -ta -i -c jlmstart 10 -c jlmdump 60 -c jlmdump 70
Connect to local machine, 10 seconds after connecting send a 'jlmstart'
command, 60 seconds after connecting send a 'jlmdump' command, 70
seconds after connecting send another 'jlmdump' command and then
enter interactive command mode.
6) rtdriver -l -c start 60 -c flush 65 -c reset
Connect to local machine, 60 seconds after connecting send a 'start'
command, 65 seconds after that send a 'flush' command followed by a
'reset' command.
**** Invocations 6 and 7 are functionally identical ****
7) rtdriver -l -ta -c start 60 -c flush 125 -c reset 125
Connect to local machine, 60 seconds after connecting send a 'start'
command, 125 seconds after connecting send a 'flush' command followed
by a 'reset' command.
**** Invocations 6 and 7 are functionally identical ****
8) rtdriver -l -b -ta -c start 60 -c flush 125 -c reset 125
Connect to all ports (that accept a connection) on the local machine,
60 seconds after connecting broadcast a 'start' command on all ports,
125 seconds after connecting broadcast a 'flush' command followed
by a 'reset' command.
**** This command allows simultaneous control of more than 1 JVM ****
9) rtdriver -n test -c start 300 -cx "java test" -c flush -c reset
Connect to machine 'test', 5 minutes (300 seconds) after connecting send
a 'start' command, immediately after that execute command "java test",
after that command completes send a 'flush' command followed by a
'reset' command.
10) rtdriver -l -c start 30 -c fgc 10 -c flush -c reset
Connect to local machine, 30 seconds after connecting send
a 'start' command, 10 seconds after that send an 'fgc' command
followed by a 'flush' command followed by a 'reset' command.
11) rtdriver -l -c start 30 -c fgc,flush,reset 10
This is very similar to invocation number 10 above except that
10 seconds after sending the 'start' command the commands 'fgc,flush,reset'
are sent as one and will be executed back-to-back-to-back by JProf.
JLM dump files are named log-jlm.# where # is a sequence number, starting with 1 (one) for the first jlmdump and incrementing by one for each subsequent jlmdump. The files are located in the java current working directory (i.e. the directory from where java was started).
Java and all Java-based trademarks are trademarks
of Sun Microsystems, Inc. in the United States, other countries, or both.
IBM is a trademark of International Business Machines Corporation in the United
States, other countries, or both.
Other company, product or service names may be trademarks or service marks of
others.
MMX, Pentium, and ProShare are trademarks or registered trademarks of Intel
Corporation in the United States, other countries, or both.