Notes - Notes on the monitoring tools

DESCRIPTION

The page documents characteristics that are common to the various jvmstat based tools.

MONITORABLE APPLICATIONS

In order to monitor a Java application with this release of the tools, the target Java application must be running on the 1.4.1, 1.4.2, or 5.0 or later HotSpot Java Virtual Machine. If the target Java application is running on the 1.4.1 HotSpot JVM, then that JVM must be started with the -XX:+UsePerfData option.

HOST IDENTIFIER

The Host Identifier, or hostid is a string that indicates the target system of the jps command. The syntax of the hostid string largely corresponds to the syntax of a URI:
[protocol:][[//]hostname][:port][/servername]
protocol
The communications protocol. If the protocol is omitted and a hostname is not specified, the default protocol is a platform specific, optimized, local protocol. If the protocol is omitted and a hostname is specified, then the default protocol is rmi.
hostname
A hostname or IP address indicating the target host. If hostname is omitted, then the target host is the local host.
port
The default port for communicating with the remote server. If the hostname is omitted or the protocol specifies an optimized, local protocol, then port is ignored. Otherwise, treatment of the port parameter is implementation specific. For the default rmi protocol the port indicates the port number for the rmiregistry on the remote host. If port is omitted, and protocol indicates rmi, then the default rmiregistry port is used (port 1099).
servername
The treatment of this parameter is implementation dependent. For the optimized, local protocol, this field is ignored. For the rmi protocol, this parameter is string representing the name of the RMI remote object on the remote host. See the -n option for the jstatd command.

VIRTUAL MACHINE IDENTIFIER

The virtual machine identifier, or vmid is a string that identifies a target JVM. The syntax of the vmid string largely corresponds to the syntax of a URI:
[protocol:][//]lvmid[@hostname][:port][/servername]
protocol
The communications protocol. If the protocol is omitted and a hostname is not specified, the default protocol is a platform specific, optimized, local protocol. If the protocol is omitted and a hostname is specified, then the default protocol is rmi.
lvmid
The local virtual machine identifier for the target JVM The lvmid is a platform specific value that uniquely indentifies a JVMachine on a system. The lvmid is the only required component of a virtual machine identifier. The lvmid is typically, but not necessarily the operating system's process identifier for the target JVM process. However, it's recommended that the jps command be used to determine the lvmid for target JVMs.
hostname
A hostname or IP address indicating the target host. If hostname is omitted, then the target host is the local host.
port
The default port for communicating with the remote server. If the hostname is omitted or the protocol specifies an optimized, local protocol, then port is ignored. Otherwise, treatment of the port parameter is implementation specific. For the default rmi protocol, the port indicates the port number for the rmiregistry on the remote host. If port is omitted, and protocol indicates rmi, then the default rmiregistry port (1099) is used.
servername
The treatment of this parameter is implementation dependent. For the optimized, local protocol, this field is ignored. For the rmi protocol, this parameter is string representing the name of the RMI remote object on the remote host. See the -n option for the jstatd command.

INTERPROCESS COMMUNICATIONS

The interprocess communications mechanism for attaching to the instrumentation exported by an instrumented JVM is platform specific. For the HotSpot JVM on the Solaris, Linux, and Windows platforms, the IPC mechanism utilizes the named shared memory facilities of the underlying platform. A shared memory region, with a backing store file in the file system name space, is created for each HotSpot JVM on a system. The file location varies depending on the native operating environment.

Solaris and Linux

The file for a particular JVM is named /tmp/hsperfdata_username/lvmid, where lvmid is the local virtual machine identifier of the target JVM. For UNIX systems, lvmid is the process identifier, or pid, for the target JVM. The username component of the path is the name of the user that corresponds to the effective user id of the target JVM process.

Access controls for the backing store files are set such that only the owner of the JVM has read/write access to the backing store file and shared memory region.

Windows

The location of the file differs depending on a number of factors, but is generally located in the directory indicated by the java.io.tmpdir system property. This property is set according to the value returned by the Windows GetTempPath() API. This interface returns the value of the %TMP% environment variable. If %TMP% is not defined, it returns the value of the %TEMP% environment variable. If neither are defined, it returns the Windows directory, which varies depending on the Windows operating system version. The java.io.tmpdir property is set to this location by default. For Windows installations, it is essential that the GetTempPath() API return the same directory location for both the monitoring tools and the target JVM. If the monitoring and monitored JVMs resolve this property to different locations, the monitoring tools will not be able to locate their target JVM processes.

The file for a particular JVM is named java.io.tmpdir\hsperfdata_username\lvmid, where lvmid is the local virtual machine identifier of the target JVM For Windows, this is the process identifier for the JVM process. The username component of the path is the name of the user that corresponds to the effective user id of the target JVM process.

Access controls for these files are set such that only the owner of the JVM process has read/write access to the backing store file and shared memory kernel object. In HotSpot 1.4.2 and later, if the java.io.tmpdir resides on a FAT or FAT32 file system, the instrumentation will be silently disabled as the file system type is not capable of providing sufficent access controls. This behavior can be overridden by setting the -XX:+PerfBypassFileSystemCheck for the target JVMs. Alternatively, the TMP environment variable can be set to volume containing an NTFS or other file system type that supports persistent access control lists.

BUGS

SEE ALSO


Copyright © 2003 Sun Microsystems, Inc. All Rights Reserved.

Sun
Java Software