| Controller reads the properties file that controls
how the profiler operates, both when the byte code is instrumented
as well as at runtime. It also opens a server socket to receive
remote commands to modify the profiler's behavior, like turning
the profiler on and off, but only if remote=on
has been specified in the profile properties. Here's a short
description of all of the properties that are supported:
profiler
Values: on, off
Default: on
Description: controls whether or not profiling information
is gathered when the VM starts. Usually you'll want this to
be on for command-line apps but off if you're profiling a web
app.
remote
Values: on, off
Default: off
Description: controls whether of not the remote interface
is enabled or not. The remote interface allows you to turn the
profiler on and off at runtime. This lets you take multiple
measurements without having to stop and start the application.
Usually you'll want this to be on for webapps
but off for command-line apps.
port
Values: any valid TCP port number
Default: 15599
Description: this controls which port the remote interface
listens on.
ClassLoaderFilter.x
Values: any valid implemtation of
com.mentorgen.tools.profile.ClassLoaderFilter
Default: If no class loader filters a specificed then
net.sourceforge.jiprof.instrument.clfilter.GenericClassLoaderFilter
is used (see also: accept-class-loaders).
Description: JIP has to know which classloader will be
loading the classes to be profiled. With command-line
apps we know what this is. However webapps and other
kinds of apps that run in a container use different classloaders.
The solution to this was to defined an interface:
ClassLoaderFilter to use in a chain of responsilbility
pattern to determine which classloader should be "hooked"
for profiling. The way this works is that you can define a number
of realizations of this interface, one of each different env.
You specify the search order by appending a number to the end
of the property. For exmaple, the standard setup is:
ClassLoaderFilter.1=com.mentorgen.tools.profile.instrument.clfilter.WebAppClassLoaderFilter
ClassLoaderFilter.2=com.mentorgen.tools.profile.instrument.clfilter.StandardClassLoaderFilter
This indicates that the WebAppClassLoaderFilter
should be called to determine if we're running in Tomcat. If that
fails, call the StandardClassLoaderFilter. Note
that currently only the Java 5(tm) and Tomcat 5.5 environments
are supported. People who would like to add support for other
environments are encouraged to do so.
thread-depth
Values: any positive integer, -1 or compact
Default: -1
Description: Call stacks can get really deep and sometimes
you only want to see a certain number of levels. This parameter
controls the number of levels you will see. The default is -1
which means that there is no limit. Another option that can
be used is compact. This will limit the call stacks
to items that have a gross time that is at least 10 ms (this
can be changed). Using
compact is nice way to limit what you see while not
imposing an arbitrary limit on the thread-depth.
thread.compact.threshold.ms
Values: any positive integer
Default: 10
Description: Modifies the call stack output to
only show nodes with the given gross time. Only works when
thread-depth is set to compact
max-method-count
Values: any positive integer, -1 or compact
Default: -1
Description: This property modifieds the section
of the profiler output that shows the most expensive method.
Giving a number greater than -1 will limit the number of methods
that are shown. -1 means no limit. compact can be usd to
show only methods with a creatin minimum gross time (the
default is 10ms but can be changed by using
method.compact.threshold.ms
method.compact.threshold.ms
Values: any positive integer
Default: 10
Description: Modifies the method output to
only show methods with the given gross time. Only works when
max-method-count is set to compact.
file
Values: the name of any valid file or directory.
Default: ./profile.txt
Description: Names the file that the profile is
sent to. If this is a directory, JIP will auto-generate
file names and
put the files in that directory. The format for the
generated file name is yyyyMMdd-HHmmss.
exclude
Values: a comman spearated list of package or class
names (class names must be fully qualified).
Default: no default
Description: the values for this property name
packages or classes to be excluded from the profile. This
is handy when you have a chatty package or class that you
just don't want to see all over the place. Note that only
classes that are loaded by the "app" class loader
are profiled to start with.
include
Values: a comman spearated list of package or class
names (class names must be fully qualified).
Default: no default
Description: the values for this property name
packages or classes to be explicitly included in the profile.
Normally, you wouldn't use this, you'd let the ClassLoaderFilter
determine which classes to include. If you don't want to see something,
use exclude. However, there
are situations where you want to exclude so much stuff, that it's easier
just to say what you want to be included. When using both exclude and include,
the include list is applied, then the exclude list is applied.
track.object.alloc
Values: on or off
Default: off
Description: control whether or not JIP tracks
object allocation.
output
Values: text, xml or both
Default: text
Description: in addition to the standard human readable
profiles, this option allows you to output the profile information
in a raw XML format.
debug
Values: on or off
Default: off
Description: when debug is turned on, text will be sent to
standard out each time a class is classloaded and inspected by
the profiler for possbile instrumentation (see
com.mentorgen.tools.profile.instrument.Transformer). If the
class is instrumented, INST, plus the class name
plus the classloader name will be sent to stddout. If the class
is not instrumented, skip, plus the class name
plus the classloader name will be sent to stddout. This is a
helpful tool when the profile you're getting (or not getting)
doesn't match what you're expecting.
In addition, text will be sent to standard error when an exception is
detected and when the profile for a method has not been completed
when the profiler terminates.
Exceptions are usually handled gracefully.
However, there are some cases where they skew the timings and therefore
the output is incorrect. Knowing that an exception is being thrown is a great
help in diagnosing problems like this.
Needing to "fixup" the profile
for one or two methods is also not that unusual. However, if the timing
for a method seems to be incorrect, knowing if the profiler needed to
fixup that method can be useful from a diagnosics perspective.
profiler-class
Values: any class name
Default: com.mentorgen.tools.profile.runtime.Profile
Description: allows the another profiling backend to be used.
output-method-signatures
Values: yes or no
Default: no
Description: When set to yes, outputs the signature
of methods. By default, the method signature is omitted from the output
to save space. However, if you're dealing with methods that have been overloaded
you need to be able to see the method signature.
clock-resolution
Values: ms or ns
Default: ns
Description: Sets the resolution of the TimeLineProfiler's clock to either milliseconds
(ms) or nanoseconds (ns). Only valid when using the
TimeLineProfiler.
output-summary-only
Values: yes or no
Default: no
Description: When set to yes the top most section of the profiler output
(the section that contains thread + call stack information) is omitted. The section can be
quite large so it is sometime desirable to not have to page through it to get to the
summary information.
accept-class-loaders
Values: A comma separated list of classloader names (you can also specify
interface names)
Default: If no values are given, java.lang.ClassLoader.getSystemClassLoader()
is used.
Description: A list of Class Loaders whose classes will be instrumented
when using net.sourceforge.jiprof.instrument.clfilter.GenericClassLoaderFilter
as the classloader filter. Note that when looking to determine if profiling should be applied
to a classloader, instanceof is used as the mode of comparison. This means, for
example, that when profiling Tomcat, you can specify org.apache.catalina.loader.Reloader
which is an interface rather than a subclass of java.lang.ClassLoader.
author:
Andrew Wilcox |
