|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.opensolaris.os.dtrace.LocalConsumer
public class LocalConsumer
Interface to the native DTrace library, each instance is a single DTrace consumer.
Nested Class Summary |
---|
Nested classes/interfaces inherited from interface org.opensolaris.os.dtrace.Consumer |
---|
Consumer.OpenFlag |
Field Summary | |
---|---|
protected ExceptionHandler |
exceptionHandler
|
protected javax.swing.event.EventListenerList |
listenerList
|
Constructor Summary | |
---|---|
LocalConsumer()
Creates a consumer that interacts with the native DTrace library on the local system. |
Method Summary | |
---|---|
void |
abort()
Aborts the background thread started by Consumer.go() . |
void |
addConsumerListener(ConsumerListener l)
Adds a listener for probe data generated by this consumer. |
void |
close()
Closes an open consumer and releases the system resources it was holding. |
Program |
compile(java.io.File program,
java.lang.String... macroArgs)
Compiles the given D program file. |
Program |
compile(java.lang.String program,
java.lang.String... macroArgs)
Compiles the given D program string. |
int |
createProcess(java.lang.String command)
Creates a process by executing the given command on the system and returns the created process ID. |
protected java.lang.Thread |
createThread()
Creates the background thread started by go() to run
this consumer. |
void |
enable()
Enables all DTrace probes compiled by this consumer. |
void |
enable(Program program)
Enables DTrace probes matching the given program and attaches information about those probes to the given program. |
protected void |
finalize()
Ensures that the close() method of this consumer has
been called before it is garbage-collected. |
protected void |
fireConsumerStarted(ConsumerEvent e)
|
protected void |
fireConsumerStopped(ConsumerEvent e)
|
protected void |
fireDataDropped(DropEvent e)
|
protected void |
fireDataReceived(DataEvent e)
|
protected void |
fireErrorEncountered(ErrorEvent e)
|
protected void |
fireIntervalBegan(ConsumerEvent e)
|
protected void |
fireIntervalEnded(ConsumerEvent e)
|
protected void |
fireProcessStateChanged(ProcessEvent e)
|
Aggregate |
getAggregate()
Gets a snapshot of all aggregations except those that have already been captured in a PrintaRecord . |
Aggregate |
getAggregate(java.util.Set<java.lang.String> includedAggregationNames)
Gets a snapshot of all the specified aggregations except those that have already been captured in a PrintaRecord . |
Aggregate |
getAggregate(java.util.Set<java.lang.String> includedAggregationNames,
java.util.Set<java.lang.String> clearedAggregationNames)
Gets a snapshot of all the specified aggregations except those that have already been captured in a PrintaRecord , with
the side effect of atomically clearing any subset of those
aggregations. |
long |
getOption(java.lang.String option)
Gets the value of a DTrace option. |
void |
getProgramInfo(Program program)
Attaches information about matching DTrace probes to the given program. |
java.lang.String |
getVersion()
Gets the version of the native DTrace library. |
void |
go()
Begin tracing and start a background thread to consume generated probe data. |
void |
go(ExceptionHandler h)
Begin tracing and start a background thread to consume generated probe data. |
void |
grabProcess(int pid)
Grabs the specified process and caches its symbol tables. |
boolean |
isClosed()
Reports whether or not this consumer is closed. |
boolean |
isEnabled()
Reports whether or not it is valid to call Consumer.go() . |
boolean |
isOpen()
Reports whether or not this consumer is open. |
boolean |
isRunning()
Reports whether or not this consumer is running. |
java.util.List<Probe> |
listProbeDetail(ProbeDescription filter)
Lists probes that match the given probe description and includes detail such as stability information about each listed probe. |
java.util.List<ProbeDescription> |
listProbes(ProbeDescription filter)
Lists probes that match the given probe description. |
java.util.List<Probe> |
listProgramProbeDetail(Program program)
Lists probes that match the given compiled program and includes detail such as stability information about each listed probe. |
java.util.List<ProbeDescription> |
listProgramProbes(Program program)
Lists probes that match the given compiled program. |
java.lang.String |
lookupKernelFunction(int address)
Gets the kernel function name for the given 32-bit kernel address. |
java.lang.String |
lookupKernelFunction(long address)
Gets the kernel function name for the given 64-bit kernel address. |
java.lang.String |
lookupUserFunction(int pid,
int address)
Gets the user function name for the given 32-bit user address and process ID. |
java.lang.String |
lookupUserFunction(int pid,
long address)
Gets the user function name for the given 64-bit user address and process ID. |
void |
open(Consumer.OpenFlag... flags)
Opens this DTrace consumer. |
void |
removeConsumerListener(ConsumerListener l)
Removes a listener for probe data generated by this consumer. |
void |
setOption(java.lang.String option)
Sets a boolean option. |
void |
setOption(java.lang.String option,
java.lang.String value)
Sets the value of a DTrace option. |
void |
stop()
Stops all tracing, as well as the background thread started by Consumer.go() to consume generated probe data. |
java.lang.String |
toString()
Gets a string representation of this consumer useful for logging and not intended for display. |
void |
unsetOption(java.lang.String option)
Unsets a boolean option. |
protected void |
work()
Called in the runnable target of the thread returned by createThread() to run this DTrace consumer. |
Methods inherited from class java.lang.Object |
---|
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
protected javax.swing.event.EventListenerList listenerList
protected ExceptionHandler exceptionHandler
Constructor Detail |
---|
public LocalConsumer()
Method Detail |
---|
public void open(Consumer.OpenFlag... flags) throws DTraceException
Consumer
setOption()
after opening the consumer. In the great
majority of cases, the consumer is opened without specifying any
flags:
consumer.open();
Subsequent calls to set options, compile DTrace programs, enable
probes, and run this consumer may be made from any thread.
open
in interface Consumer
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.compile(File program, String[] macroArgs)
,
Consumer.compile(String program, String[] macroArgs)
,
Consumer.enable()
,
Consumer.go()
public Program compile(java.lang.String program, java.lang.String... macroArgs) throws DTraceException
Consumer
$1
.
compile
in interface Consumer
program
- program stringmacroArgs
- macro substitutions for $n placeholders
embedded in the given D program: macroArgs[0]
replaces
all occurrences of $1
, macroArgs[1]
replaces all
occurrences of $2
, and so on. $0
is
automatically replaced by the executable name and should not be
included in the macroArgs
parameter. See the
Macro Arguments section of the Scripting
chapter of the Solaris Dynamic Tracing Guide.
Program
identifier that may be passed
to enable()
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.compile(File program, String[] macroArgs)
public Program compile(java.io.File program, java.lang.String... macroArgs) throws DTraceException, java.io.IOException, java.lang.SecurityException
Consumer
$1
.
compile
in interface Consumer
program
- program filemacroArgs
- macro substitutions for $n placeholders
embedded in the given D program: macroArgs[0]
replaces
all occurrences of $1
, macroArgs[1]
replaces all
occurrences of $2
, and so on. $0
is
automatically set to the name of the given file and should not be
included in the macroArgs
parameter. See the
Macro Arguments section of the Scripting
chapter of the Solaris Dynamic Tracing Guide.
Program
identifier that may be passed
to enable()
DTraceException
- if an exception occurs in the native
DTrace library
java.io.FileNotFoundException
- if the given program file cannot be
opened
java.io.IOException
- if an I/O error occurs while reading the
contents of the given program file
java.lang.SecurityException
- if a security manager exists and its
checkRead()
method denies read access to the fileConsumer.compile(String program, String[] macroArgs)
public void enable() throws DTraceException
Consumer
enable()
with no argument to enable everything this consumer has
compiled so far (most commonly a single program, the only one to
be compiled). Call with one Program
at a time if you
need information about enabled probes specific to each program.
enable
in interface Consumer
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.enable(Program program)
public void enable(Program program) throws DTraceException
Consumer
enable
in interface Consumer
program
- A Program
identifier returned by compile(String
program, ...)
or compile(File program, ...)
: If the given program is
null
, the call has the same behavior as Consumer.enable()
with no argument; if the given program is non-null, the call
enables only those probes matching that program. In the latter
case, the Program
parameter is modified as a way of
passing back information about the given program and its matching
probes, including program stability.
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.compile(String program, String[] macroArgs)
,
Consumer.compile(File program, String[] macroArgs)
,
Consumer.enable()
,
Consumer.getProgramInfo(Program program)
public void getProgramInfo(Program program) throws DTraceException
Consumer
Consumer.enable(Program program)
but without
enabling the probes.
getProgramInfo
in interface Consumer
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.compile(String program, String[] macroArgs)
,
Consumer.compile(File program, String[] macroArgs)
,
Consumer.enable(Program program)
public void setOption(java.lang.String option) throws DTraceException
Consumer
setOption
in interface Consumer
DTraceException
- if a value is expected for the given
option, or if the option is otherwise invalidConsumer.setOption(String option, String value)
,
Consumer.unsetOption(String option)
public void unsetOption(java.lang.String option) throws DTraceException
Consumer
unsetOption
in interface Consumer
DTraceException
- if the given option is not a boolean
option, or if the option is otherwise invalidConsumer.setOption(String option)
public void setOption(java.lang.String option, java.lang.String value) throws DTraceException
Consumer
compile(String
program, ...)
or compile(File program, ...)
in order to have an effect
on compilation. Some runtime options including switchrate
and aggrate
are settable while a consumer is running; others must be set
before calling Consumer.go()
. See the
Options and Tunables chapter of the Solaris Dynamic
Guide for information about specific options.
setOption
in interface Consumer
DTraceException
- for any of the following:
go()
has been called to start this consumer, and the
option is not settable on a running consumer (some runtime
options, including switchrate
and
aggrate
are settable while the consumer is
running)Consumer.open(OpenFlag[] flags)
,
Consumer.getOption(String option)
,
Option
public long getOption(java.lang.String option) throws DTraceException
Consumer
getOption
in interface Consumer
Option.UNSET
. If the given option is a size
option, the returned value is in bytes. If the given option is a
time option, the returned value is in nanoseconds. If the
given option is bufpolicy
, the returned
value is one of BUFPOLICY_RING
,
BUFPOLICY_FILL
, or BUFPOLICY_SWITCH
. If the given option
is bufresize
, the returned value is one
of BUFRESIZE_AUTO
or BUFRESIZE_MANUAL
.
DTraceException
- if the given option is invalidConsumer.setOption(String option)
,
Consumer.unsetOption(String option)
,
Consumer.setOption(String option, String value)
,
Option
public final boolean isOpen()
Consumer
isOpen
in interface Consumer
true
if and only if open()
has been called on this consumer and Consumer.close()
has notpublic final boolean isEnabled()
Consumer
Consumer.go()
.
isEnabled
in interface Consumer
true
if and only if at least one program has been
compiled, all compiled programs have been enabled, go()
has not already been called, and Consumer.close()
has not been
calledpublic final boolean isRunning()
Consumer
Consumer.go()
before this consumer actually
starts running (listeners are notified by the consumerStarted()
method).
isRunning
in interface Consumer
true
if this consumer is running, false
otherwisepublic final boolean isClosed()
Consumer
Note that a closed consumer is different from a consumer that has not yet been opened.
isClosed
in interface Consumer
true
if Consumer.close()
has been called on this
consumer, false
otherwiseprotected final void work()
createThread()
to run this DTrace consumer.
createThread()
protected java.lang.Thread createThread()
go()
to run
this consumer. Override this method if you need to set
non-default Thread
options or create the thread in a
ThreadGroup
. If you don't need to create the thread
yourself, set the desired options on super.createThread()
before returning it. Otherwise, the Runnable
target of
the created thread must call work()
in order to run this
DTrace consumer. For example, to modify the default background
consumer thread:
protected Thread
createThread()
{
Thread t = super.createThread();
t.setPriority(Thread.MIN_PRIORITY);
return t;
}
Or if you need to create your own thread:
protected Thread createThread() { Runnable target = new Runnable() { public void run() { work(); } }; String name = "Consumer " + UserApplication.sequence++; Thread t = new Thread(UserApplication.threadGroup, target, name); return t; }Do not start the returned thread, otherwise
go()
will
throw an IllegalThreadStateException
when it tries to
start the returned thread a second time.
public void go() throws DTraceException
Consumer
go
in interface Consumer
java.lang.IllegalThreadStateException
- if a subclass calls Thread.start()
on the value of createThread()
DTraceException
- if an exception occurs in the native
DTrace librarycreateThread()
public void go(ExceptionHandler h) throws DTraceException
Consumer
go
in interface Consumer
java.lang.IllegalThreadStateException
- if a subclass calls Thread.start()
on the value of createThread()
DTraceException
- if an exception occurs in the native
DTrace librarycreateThread()
public void stop()
Consumer
Consumer.go()
to consume generated probe data. A stopped
consumer cannot be restarted. It is necessary to close()
a stopped consumer to release the system resources it holds.
A consumer may stop on its own in response to the exit()
action (see exit()
in the
Special Actions section of the Actions and
Subroutines chapter of the Solaris Dynamic Tracing
Guide). Similarly, a consumer stops automatically if it has
at least one target process and all its target processes have
completed (see createProcess()
and grabProcess()
). A consumer also stops automatically if it
encounters an exception while consuming probe data. In these
cases it is not necessary to call stop()
. If a consumer
stops for any reason (an explicit call to stop()
or any
of the reasons just given), listeners are notified through the
consumerStopped()
method.
Note that a call to stop()
blocks until the background
thread started by go()
actually stops. After stop()
returns, a call to Consumer.isRunning()
returns false
. If a DTraceException
is thrown while stopping
this consumer, it is handled by the handler passed to Consumer.go(ExceptionHandler h)
(or a default handler if none is
specified).
stop
in interface Consumer
java.lang.IllegalThreadStateException
- if attempting to stop()
a running consumer while holding the lock on that
consumerConsumer.go()
,
Consumer.abort()
,
Consumer.close()
public void abort()
Consumer
Consumer.go()
. abort()
is effectively the same as Consumer.stop()
except that
it does not block (i.e. it does not wait until the background
thread actually stops). Consumer.isRunning()
is likely true
immediately after a call to abort()
, since an
aborted consumer stops at a time specified as later.
Specifically, a call to abort()
stops tracing just before
the next intervalBegan()
event and stops consuming probe data by the
subsequent intervalEnded()
event. When the aborted consumer actually
stops, listeners are notified in the consumerStopped()
method, where it is convenient to Consumer.close()
the stopped consumer after requesting the final
aggregate.
The abort()
and stop()
methods have slightly
different behavior when called just after go()
but
before the consumer actually starts running: It is
possible to stop()
a consumer before it starts running
(resulting in a consumerStopped()
event without a
matching consumerStarted()
event), whereas an aborted
consumer will not stop until after it starts running, when it
completes a single interval (that interval does not include
sleeping to wait for traced probe data). Calling abort()
before go()
is legal and has the same effect as calling
it after go()
and before the consumer starts running.
The last behavior follows from the design: You do not know the
state of a consumer after calling abort()
, nor is it
necessary to know the state of a consumer before calling abort()
. That may be preferable, for example, when you want to
abort a consumer opened and started in another thread.
abort
in interface Consumer
Consumer.stop()
public void close()
Consumer
close()
will Consumer.stop()
it automatically. A closed consumer cannot be
reopened. Closing a consumer that has not yet been opened makes
it illegal to open that consumer afterwards. It is a no-op to
call close()
on a consumer that is already closed.
close
in interface Consumer
java.lang.IllegalThreadStateException
- if attempting to close()
a running consumer while holding the lock on that
consumerConsumer.open(OpenFlag[] flags)
public void addConsumerListener(ConsumerListener l)
Consumer
addConsumerListener
in interface Consumer
public void removeConsumerListener(ConsumerListener l)
Consumer
removeConsumerListener
in interface Consumer
public Aggregate getAggregate() throws DTraceException
Consumer
PrintaRecord
. Does not clear
any aggregation.
Provides a programmatic alternative to the printa(
)
action (see
printa()
in the Output Formatting
chapter of the Solaris Dynamic Tracing Guide).
getAggregate
in interface Consumer
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.getAggregate(Set includedAggregationNames, Set
clearedAggregationNames)
public Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames) throws DTraceException
Consumer
PrintaRecord
. Does
not clear any aggregation.
Provides a programmatic alternative to the printa(
)
action (see
printa()
in the Output Formatting
chapter of the Solaris Dynamic Tracing Guide).
getAggregate
in interface Consumer
includedAggregationNames
- if null
, all available
aggregations are included; if non-null, only those aggregations
specifically named by the given set are included
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.getAggregate(Set includedAggregationNames, Set
clearedAggregationNames)
public Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames, java.util.Set<java.lang.String> clearedAggregationNames) throws DTraceException
Consumer
PrintaRecord
, with
the side effect of atomically clearing any subset of those
aggregations. Clearing an aggregation resets all of its values
to zero without removing any of its keys. Leave aggregations
uncleared to get running totals, otherwise specify that an
aggregation be cleared to get values per time interval. Note
that once an aggregation is captured in a PrintaRecord
(as a result of the printa()
action), it is no longer
available to the getAggregate()
method.
Provides a programmatic alternative to the printa(
) (see
printa()
in the Output Formatting
chapter of the Solaris Dynamic Tracing Guide) and clear()
actions.
getAggregate
in interface Consumer
includedAggregationNames
- if null
, all available
aggregations are included; if non-null, only those aggregations
specifically named by the given set are includedclearedAggregationNames
- if null
, all available
aggregations are cleared; if non-null, only those aggregations
specifically named by the given set are cleared
DTraceException
- if an exception occurs in the native
DTrace librarypublic int createProcess(java.lang.String command) throws DTraceException
Consumer
Consumer.go()
so that the process waits
to do anything until this consumer has started tracing (allowing
a process to be traced from the very beginning of its execution).
The macro variable $target
in a D program will be
replaced by the process ID of the created process. When the
created process exits, this consumer notifies listeners through
the processStateChanged()
method.
See the Target Process ID section of the Scripting chapter of the Solaris Dynamic Tracing Guide.
createProcess
in interface Consumer
command
- a string whose first token is assumed to be the
name of the command and whose subsequent tokens are the arguments
to that command.
DTraceException
- if the process cannot be createdConsumer.grabProcess(int pid)
public void grabProcess(int pid) throws DTraceException
Consumer
$target
in a D program will be replaced by
the process ID of the grabbed process. When the specified
process exits, this consumer notifies listeners through the
processStateChanged()
method.
See the Target Process ID section of the Scripting chapter of the Solaris Dynamic Tracing Guide.
grabProcess
in interface Consumer
pid
- process ID of the process to be grabbed
DTraceException
- if the process cannot be grabbedConsumer.createProcess(String command)
public java.util.List<ProbeDescription> listProbes(ProbeDescription filter) throws DTraceException
Consumer
ProbeDescription
for information about pattern syntax and
wildcarding.
listProbes
in interface Consumer
filter
- use ProbeDescription.EMPTY
to get all
probes, otherwise get only those probes that match the given
filter
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.open(OpenFlag[] flags)
,
Consumer.close()
,
Consumer.listProbeDetail(ProbeDescription filter)
,
Consumer.listProgramProbes(Program program)
public java.util.List<Probe> listProbeDetail(ProbeDescription filter) throws DTraceException
Consumer
listProbeDetail
in interface Consumer
filter
- use ProbeDescription.EMPTY
to get all
probes, otherwise get only those probes that match the given
filter
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.listProbes(ProbeDescription filter)
,
Consumer.listProgramProbeDetail(Program program)
public java.util.List<ProbeDescription> listProgramProbes(Program program) throws DTraceException
Consumer
listProgramProbes
in interface Consumer
program
- a Program
identifier returned by compile(String
program, ...)
or compile(File program, ...)
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.listProbes(ProbeDescription filter)
public java.util.List<Probe> listProgramProbeDetail(Program program) throws DTraceException
Consumer
listProgramProbeDetail
in interface Consumer
program
- a Program
identifier returned by compile(String
program, ...)
or compile(File program, ...)
DTraceException
- if an exception occurs in the native
DTrace libraryConsumer.listProgramProbes(Program program)
,
Consumer.listProbeDetail(ProbeDescription filter)
public java.lang.String lookupKernelFunction(int address)
Consumer
lookupKernelFunction
in interface Consumer
address
- 32-bit kernel function address, such as the value
of a Tuple
member in an AggregationRecord
to be
converted for display
module`function
module`function+offset
module`address
address
module
and function
are names, and offset
and address
are
integers in hexadecimal format preceded by "0x
". offset
is the number of bytes from the beginning of the
function, included when non-zero. address
is simply the
hex form of the input paramater, returned when function lookup
fails. The exact details of this format are subject to change.Consumer.lookupKernelFunction(long address)
public java.lang.String lookupKernelFunction(long address)
Consumer
lookupKernelFunction
in interface Consumer
address
- 64-bit kernel function address
Consumer.lookupKernelFunction(int address)
public java.lang.String lookupUserFunction(int pid, int address)
Consumer
lookupUserFunction
in interface Consumer
pid
- ID of the user process containing the addressed
functionaddress
- 32-bit user function address, such as the value
of a Tuple
member in an AggregationRecord
to be
converted for display.
module`function
module`function+offset
module`address
address
module
and function
are names, and offset
and address
are
integers in hexadecimal format preceded by "0x
". offset
is the number of bytes from the beginning of the
function, included when non-zero. address
is simply the
hex form of the input paramater, returned when function lookup
fails. The exact details of this format are subject to change.Consumer.lookupUserFunction(int pid, long address)
public java.lang.String lookupUserFunction(int pid, long address)
Consumer
lookupUserFunction
in interface Consumer
pid
- ID of the user process containing the addressed
functionaddress
- 64-bit user function address
Consumer.lookupUserFunction(int pid, int address)
public java.lang.String getVersion()
Consumer
getVersion
in interface Consumer
dtrace(1M)
with the -V
option)protected void fireDataReceived(DataEvent e) throws ConsumerException
ConsumerException
protected void fireDataDropped(DropEvent e) throws ConsumerException
ConsumerException
protected void fireErrorEncountered(ErrorEvent e) throws ConsumerException
ConsumerException
protected void fireProcessStateChanged(ProcessEvent e) throws ConsumerException
ConsumerException
protected void fireConsumerStarted(ConsumerEvent e)
protected void fireConsumerStopped(ConsumerEvent e)
protected void fireIntervalBegan(ConsumerEvent e)
protected void fireIntervalEnded(ConsumerEvent e)
public java.lang.String toString()
class-name[property1 = value1, property2 = value2]
toString
in class java.lang.Object
protected void finalize()
close()
method of this consumer has
been called before it is garbage-collected. The intended safety
net is weak because the JVM does not guarantee that an object
will be garbage-collected when it is no longer referenced. Users
of the API should call close()
to ensure that all
resources associated with this consumer are reclaimed in a timely
manner.
finalize
in class java.lang.Object
close()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |