File: README

----------------------------------------------------------------------------
  Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
 
  The contents of this file are subject to the terms of the
  Common Development and Distribution License, Version 1.0 only.
  See the file LICENSING.NOTICE in this distribution or
  http://www.opensolaris.org/license/ for details.
----------------------------------------------------------------------------

		Dynamic Tracing (DTrace) VM Agents
		----------------------------------
Source for a pair of VM agent libraries that create DTrace probes. 
One is written using JVM TI and the other written using JVMPI.

These libraries will need to be found, so you will need to set
LD_LIBRARY_PATH so that they are found.  I would recommend:

    cd YOUR_OWN_PRIVATE_DVM_STORAGE_AREA
    unzip dvm.zip
    if ( "`uname -p`" == sparc ) then
        setenv LD_LIBRARY_PATH_64 `pwd`/build/sparcv9/lib
        setenv LD_LIBRARY_PATH_32 `pwd`/build/sparc/lib
    else
        setenv LD_LIBRARY_PATH_64 `pwd`/build/amd64/lib
        setenv LD_LIBRARY_PATH_32 `pwd`/build/i386/lib
    endif

Usage:

    java [-d64] -Xrundvm[tp]i[:options] ...

Where options are:
	help		Prints a help message
	all		same as: unloads,allocs,stats,methods
	unloads		track class unloads
	allocs		track object allocations and frees
	stats		generate heap stats after each GC
	methods		generate method entry exit events
	exclude=name	exclude class names
	dynamic=<path>	Enable the dynamic DVM option
default is none of unloads, allocs, stats, methods, or dynamic.

With JDK 5.0 and newer, you can set an environment variable so that all
VM's started will see, e.g. in csh
    
    setenv JAVA_TOOL_OPTIONS "-Xrundvmti:all"

See http://java.sun.com/j2se/1.5.0/docs/guide/jvmti/jvmti.html#tooloptions
for more information on JAVA_TOOL_OPTIONS.

Also in JDK 5.0 and on Solaris(tm) 10, there is a jps utility 
(/usr/java/bin/jps) that will quickly identify what processes represent VM's.

Shared library names are libdvmpi.so and libdvmti.so.

The dvmti agent will work with JDK 5.0 and newer JDK's, but may not be 
necessary in the JDK 6.0 or newer JDK's since DTrace probes will be directly 
added to those VM's and the JDK 6.0 probes will likely be more efficient.

The dvmpi agent will work with JDK 1.4.2 and JDK 5.0 but will have some
limitations regarding which GC can be used, and what early VM events will
be seen.

The dvmti agent will utilize BCI (Byte Code Injection) where needed and
will need a jar file, that should be located in the same directory as the
shared library.
The dvmpi agent will utilize the slow object allocation path where needed.

You will likely be unable to compare the two agents, they will behave
slightly differently.

The dynamic DVM option is designed to reduce the probe-effect of the DVM
agent by disabling or enabling the most costly codepaths associated
with having the DTrace probes active (mostly this is the code required to
make the JNI call and to resolve the class, method, and object names - 
the DTrace probes themselves are trivial). This is especially useful
for very large applications or for applications that run inside an
application server.

This feature is disabled by default which means that the DVM provider
is in full effect (DTrace probes will fire) when the VM is started.
The reason for this is to ensure that early events can be caught, if 
needed, without relying on the DVM probes to potentially become
active too late.

To use the dynamic DVM provider option, the following steps should be
taken:

1) Create a named pipe using mknod(1M). For security purposes, one should
ensure that the pipe is in a safe directory and only readable and writeable
by the uid that will also run the VM. The worst that could happen is that
DVM be turned on/off, but it is a wise decision.

ex: 
	mknod /app/prvt/ddvmpipe
	chmod 600 /app/prvt/ddvmpipe

2) Start your Java process with the DVM agent and use the dynamic option.
This can be done wither on the command line or with the environment
variable.

ex:
	setenv JAVA_TOOL_OPTIONS "-Xrundvmti:all,dynamic=/app/prvt/ddvmpipe"

3) When you are ready to disable (or enable) the DTrace probes, simply echo
a single character to the named pipe.

ex:
	echo d >> /app/prvt/ddvmpipe

This will change the state of the DVM agent to the opposite of what it
is currently. This can be done as often as you like.

If you wish to disable DVM DTrace probes very early in startup, simply swap
the order of actions 2 and 3 (echo to the name pipe first). The echo will
block until the DVM agent thread responsible for the dynamic feature
consumes the byte. This will disable the DVM probes as soon as that thread
is started and scheduled.

In testing, this reduced startup time of a complex application from over 15
minutes to less than 45 seconds - YMMV.



To Build and create a source bundle
-----------------------------------
Works with either Sun make or GNU make.

From a bundle:
    REPO=<new directory>
    rm -f -r ${REPO}
    mkdir ${REPO}
    cp dvm.zip ${REPO}
    cd ${REPO}; unzip dvm.zip
    cd ${REPO}/make; make
Results will be in the build directory. Both 64 and 32 bit versions are built.

To Test
-------
login as root or have dtrace_proc privilege.
export DISPLAY=<display needed to run Java2Demo as test, xhost + the display>
cd ${REPO}/make; make test

Issues
------
JVMPI does not provide enough information on object free to provide a 
classname or size.
JVMPI does not provide enough information on monitor events to provide
a thread name.
There is no monitor name to be had.