
readme.txt - $Version$


This is a simple tutorial on using the JBoss Profiler.


LICENSING

This software is distributed under the terms of the LGPL license.


BUILDING THE PROFILER

1.  Build using ant.  The built files will appear under the build/ directory.

2.  To compile the native library (DLL or .so), you have to use gcc. Under
Windows use Cygwin with gcc installed and run the compile.sh script in the
native/win32 directory.  Under Linux/Unix, run the compile.sh script in
the native/linux or native/solaris directory.


INSTALLATION

1.  Once built, put jbossInspector.dll in your PATH (if you are using Windows)
or libjbossInspector.so in your LD_LIBRARY_PATH (if you are using Linux/Unix.)

2.  Copy the jboss-profiler.war file on your analysis system.  Deploy under a
standard web container.  The jboss-provider.war file provides a front-end for
analysis.  When loaded, the front-end keeps the profile data loaded entirely
in memory.  You may have to allocate extra memory for the web container.
(There is a class named "FileCollection" which uses the Tomcat's temporary file
system as a virtual memory buffer.  You might want to clean that directory
after running Jboss Profiler.)


USING THE PROFILER

1.  Add the -XrunjbossInspector:<directory>,<options...> as a parameter to
your JVM. (Sun's or IBM's JVM)

  Possible options include:
    start=<prefix name>
    include=<prefix name>
    ignore=<prefix name>
    socket=<server|IP>:<port>
    uniqueNames=true
        Useful for running test cases
    wakeupOnStartup=true
        Start the profiler always after the JVM start
        This option is used to be used in conjunction with dpConsole.jar. If
        you use that option you have to include dpConsole.jar on the class-path of your
        application server.
    memory=true|false (default=true)
        Disable the memory profiler.
        If this options is disable the profiler wouldn't capture any allocations events during data gathering

  Example use:
     java -XrunjbossInspector:/tmp,include=org.jboss,ignore=*,start=org.jboss.mq.MQServer
  
  These options only capture data for org.jboss classes (everything else is
  ignored with the ignore=* option).  The "start" option will capture data only
  after org.jboss.mq.MQServer appears on your stack trace.

When running under JBoss, you can set the environment variable JAVA_OPTS to
this parameter.  Example use under Unix:

  $ export JAVA_OPTS=-XrunjbossInspector:/tmp,include=org.ex,ignore=*,start=org.ex.Main
  
2.  Start the data capturing.  The profiler sleeps until you send a signal.

If you use Sun's JVM, send a signal using "kill -3" to start and another "kill
-3" to finish capturing.  (You have only one shot, as you can use start option
to tell what you need to profile).  CTRL-BREAK on Windows also sends the same
signal.

If you use IBM's JVM, use the option socket=server:port (e.g. localhost:1000). Before
starting your JVM, execute:
     java -jar dpConsole.jar 1000
Then tell the dpConsole.jar what PID you want to signal to start.

Alternatively, if you're running the profiler under JBoss, you can deploy
either jboss-profiler-noAOP.sar or jboss-profiler.sar and stop, start, pause
the data capturing through JMX and the JMX console.  The MBean has the
javax.management.ObjectName jboss.profiler:mbean=Native-profiler .

[TODO : discuss use of AOP capturing]

3.  After you have captured your .log.gz files you have to process them by
using the front-end application.  Access the analysis tool you installed
previously.



