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]>
<[-s | -js | -jsl] <#sec>>
<[-f | -jd] #sec>
<[-r | -rs | -rd | -rds] #sec>
<-ta> <<[-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 - 8891,
to connect to.
* Default port number is 8888.
-b Causes RTDriver to attempt to connect to all valid ports
(8888 - 8891) 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.
***** Automatic Start options *****
-s <#sec> Automatically send start command upon connecting to host.
-js <#sec> Automatically send jlmstart command upon connecting to host.
-jsl <#sec> Automatically send jlmstartlite command upon connecting to host.
* If a delay value (#sec) is given, the start will be sent
after that many seconds.
* If no delay value is given, the start is sent immediately.
* Delay value is in seconds and must be a decimal number.
***** Automatic Dump options *****
-jd #sec Automatically send jlmdump command after connecting to host.
* Time delay is in seconds and must be a non-zero decimal number.
* If -s is specified then the flush is sent #sec after the start.
* If -js/jsl is specified then the jlmdump is sent #sec after
the start.
***** Automatic Stop options *****
-rs #sec Run for given number of seconds and send a "stop" command.
-r #sec Same as -rs. Kept for backwards compatibility.
-rd #sec Run for given number of seconds and send "dump" command.
-rds #sec Run for given number of seconds and send "dump" command,
followed by a "stop" command.
* If -s also specified the commands sent are flush and stop.
* If -js/jsl also specified the commands sent are jlmdump
and jlmstop.
* Run time is in seconds and must be a non-zero decimal number.
* -r options are only allowed with -s, -js or -jsl.
* The "stop" command is sent #sec after the previous command.
Previous command can be either a "start", or if -f/jd is
specified, a "dump".
* Interactive command mode is never entered if -r* is specified.
***** User command control 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 flush
- Is not the same as:
-c fgc,flush
- "-c fgc -c flush" are sent as two commands and there is
a delay (probably very small) between sending them.
- "-c fgc,flush" is sent as one command, which JProf splits
into fgc followed by flush.
* 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,
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.
JProf commands
--------------
start<=#> - Start collection. If '#', start after '#' seconds
off - Stop collection and disable all JVMPI/TI events
stop - Stop data collection, write data to file, terminate
JVM and exit RTDriver
gc - Request immediate garbage collection
hds|heapdump=1 - Request 'summary' heap dump
hd|heapdump=2 - Request 'detailed' heap dump
JLM commands
------------
jlm|jlmstart - Start JLM collection *WITH* hold time accounting
jlml|jlmlitestart - Start JLM collection *WITHOUT* hold time accounting
jstop|jlmstop - Turn off JLM
jd|jlmdump - Request JLM dump
jdr|jlmdumpr - Request JLM dump and Reset JLM
Interactive command notes:
--------------------------
* 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 a HEAPDUMP.
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 8891, 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 8891). Commands will be sent (broadcast) to
all ports to which a successful connection was made.
* When using RTDriver with JLM, valid options are:
Start: one of -js or -jsl
Dump: -jd
Stop: one of -r, -rs, -rd or -rds
* 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.
* Interactive command mode is not entered if a -r* option is specified or
if a -c* option is specified.
* The net result of -s, -js or -jsl and -r is that interactive command mode
is not used. RTDriver automatically sends the "start" command followed by
"stop" command after the specified run time.
* The automatic command sequence is as follows:
- If -s, -js or -jsl is specified then the appropriate "start" command
is sent #sec after connecting to host.
- If -f or -jd is specified then the appropriate "dump" is sent #sec after
the "start" command is sent (if one of the start options was specified).
- If -r* is specified then the appropriate "stop"/"dump" command sequence
is sent #sec after the previous command (either "start" or "dump")
was sent.
* You cannot mix user commands (-c options) with other automatic commands
(-s, -f, -js, etc).
* You can create fairly complex automatic command sequences by using user
commands.
* Commands specified with the -cx option are executed using the system()
library function. RTDriver will not continue until the command completes.
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 -n test002 -s
Connect to machine 'test002', send a 'start' command and then
enter interactive command mode.
4) rtdriver -a 9.3.55.124 -s -r 50
Connect to machine '9.2.55.124', send a 'start' command
wait 50 seconds and then send a 'stop' command. Interactive
command mode *IS NOT* entered.
5) rtdriver -n expresso -p 8889 -s 15 -rds 120
Connect to machine 'expresso' on port 8889, wait 15 seconds, send
a 'start' command, wait 120 seconds and then send a 'flush' command
followed by a 'stop' command.
Interactive command mode *IS NOT* entered.
6) rtdriver -n latte -s 15 -f 100 -r 1
Connect to machine 'latte', wait 15 seconds, send a 'start' command,
wait 100 seconds, send a 'flush' command, wait 1 second, send a 'stop'
command.
Interactive command mode *IS NOT* entered.
7) rtdriver -n capuccino -js 10 -r 120
Connect to machine 'capuccino', wait 10 seconds, send a 'jlmstart'
command, wait 120 seconds and then send a 'jlmstop' command.
Interactive command mode *IS NOT* entered.
8) rtdriver -l -js 10 -jd 50 -rds 10
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.
Interactive command mode *IS NOT* entered.
**** Invocations 8, 9 and 10 are functionally identical ****
9) 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.
Interactive command mode *IS NOT* entered.
**** Invocations 8, 9 and 10 are functionally identical ****
10) 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.
Interactive command mode *IS NOT* entered.
**** Invocations 8, 9 and 10 are functionally identical ****
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.