|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Consumer
Interface to the native DTrace library, each instance is a single
DTrace consumer. To consume the output of DTrace program actions,
register a probe data
listener
. To get a snapshot of all aggregations in a D program on
your own programmatic interval without relying on DTrace actions to
generate that output, use the getAggregate()
method.
ProbeData
,
Aggregate
Nested Class Summary | |
---|---|
static class |
Consumer.OpenFlag
Optional flags passed to open() . |
Method Summary | |
---|---|
void |
abort()
Aborts the background thread started by 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. |
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. |
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 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 go() to consume generated probe data. |
void |
unsetOption(java.lang.String option)
Unsets a boolean option. |
Method Detail |
---|
void open(Consumer.OpenFlag... flags) throws DTraceException
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.
java.lang.NullPointerException
- if any of the given open flags is
null
java.lang.IllegalArgumentException
- if any of the given flags are
mutually exlusive
java.lang.IllegalStateException
- if this consumer is closed or has
already been opened
DTraceException
- if an exception occurs in the native
DTrace librarycompile(File program, String[] macroArgs)
,
compile(String program, String[] macroArgs)
,
enable()
,
go()
Program compile(java.lang.String program, java.lang.String... macroArgs) throws DTraceException
$1
.
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()
java.lang.NullPointerException
- if the given program string or any
of the given macro arguments is null
java.lang.IllegalStateException
- if called before open()
or after go()
, or if the
consumer is closed
DTraceException
- if an exception occurs in the native
DTrace librarycompile(File program, String[] macroArgs)
Program compile(java.io.File program, java.lang.String... macroArgs) throws DTraceException, java.io.IOException, java.lang.SecurityException
$1
.
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()
java.lang.NullPointerException
- if the given program file or any of
the given macro arguments is null
java.lang.IllegalStateException
- if called before open()
or after go()
, or if the
consumer is closed
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 filecompile(String program, String[] macroArgs)
void enable() throws DTraceException
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.
java.lang.IllegalStateException
- if called before compiling at least
one program, or if any compiled program is already enabled, or if
go()
was already called, or if this consumer is closed
DTraceException
- if an exception occurs in the native
DTrace libraryenable(Program program)
void enable(Program program) throws DTraceException
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 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.
java.lang.IllegalArgumentException
- if the given program is non-null
and not compiled by this Consumer
java.lang.IllegalStateException
- if the given program is already
enabled (or if the given program is null
and any
program is already enabled), or if go()
was already
called, or if this consumer is closed
DTraceException
- if an exception occurs in the native
DTrace librarycompile(String program, String[] macroArgs)
,
compile(File program, String[] macroArgs)
,
enable()
,
getProgramInfo(Program program)
void getProgramInfo(Program program) throws DTraceException
enable(Program program)
but without
enabling the probes.
java.lang.NullPointerException
- if the given program is null
java.lang.IllegalArgumentException
- if the given program was not
compiled by this Consumer
java.lang.IllegalStateException
- if called after close()
DTraceException
- if an exception occurs in the native
DTrace librarycompile(String program, String[] macroArgs)
,
compile(File program, String[] macroArgs)
,
enable(Program program)
void setOption(java.lang.String option) throws DTraceException
java.lang.NullPointerException
- if the given option is null
DTraceException
- if a value is expected for the given
option, or if the option is otherwise invalid
java.lang.IllegalStateException
- if called before open()
or after close()
, or if
the given option is a boolean compile-time option and go()
has already been called (see Option
for a
breakdown of runtime and compile-time options)setOption(String option, String value)
,
unsetOption(String option)
void unsetOption(java.lang.String option) throws DTraceException
java.lang.NullPointerException
- if the given option is null
DTraceException
- if the given option is not a boolean
option, or if the option is otherwise invalid
java.lang.IllegalStateException
- if called before open()
or after close()
, or if
the given option is a boolean compile-time option and go()
has already been called (see Option
for a
breakdown of runtime and compile-time options)setOption(String option)
void setOption(java.lang.String option, java.lang.String value) throws DTraceException
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 go()
. See the
Options and Tunables chapter of the Solaris Dynamic
Guide for information about specific options.
java.lang.NullPointerException
- if the given option or value is
null
java.lang.IllegalStateException
- if called before open()
or after close()
, or if
the given option is a boolean compile-time option and go()
has already been called (see Option
for a breakdown
of runtime and compile-time options)
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)open(OpenFlag[] flags)
,
getOption(String option)
,
Option
long getOption(java.lang.String option) throws DTraceException
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
.
java.lang.NullPointerException
- if the given option is null
java.lang.IllegalStateException
- if called before open()
or after close()
DTraceException
- if the given option is invalidsetOption(String option)
,
unsetOption(String option)
,
setOption(String option, String value)
,
Option
boolean isOpen()
true
if and only if open()
has been called on this consumer and close()
has notboolean isEnabled()
go()
.
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 close()
has not been
calledboolean isRunning()
go()
before this consumer actually
starts running (listeners are notified by the consumerStarted()
method).
true
if this consumer is running, false
otherwiseboolean isClosed()
Note that a closed consumer is different from a consumer that has not yet been opened.
true
if close()
has been called on this
consumer, false
otherwisevoid go() throws DTraceException
java.lang.IllegalStateException
- if not isEnabled()
DTraceException
- if an exception occurs in the native
DTrace librarygo(ExceptionHandler h)
,
open(OpenFlag[] flags)
,
compile(String program, String[] macroArgs)
,
compile(File program, String[] macroArgs)
,
enable()
,
stop()
,
close()
void go(ExceptionHandler h) throws DTraceException
java.lang.IllegalStateException
- if not isEnabled()
DTraceException
- if an exception occurs in the native
DTrace librarygo()
void stop()
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 isRunning()
returns false
. If a DTraceException
is thrown while stopping
this consumer, it is handled by the handler passed to go(ExceptionHandler h)
(or a default handler if none is
specified).
java.lang.IllegalStateException
- if called before go()
or
if stop()
was already calledgo()
,
abort()
,
close()
void abort()
go()
. abort()
is effectively the same as stop()
except that
it does not block (i.e. it does not wait until the background
thread actually stops). 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 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.
stop()
void close()
close()
will 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.
open(OpenFlag[] flags)
void addConsumerListener(ConsumerListener l)
void removeConsumerListener(ConsumerListener l)
Aggregate getAggregate() throws DTraceException
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).
java.lang.IllegalStateException
- if called before go()
or
after close()
DTraceException
- if an exception occurs in the native
DTrace librarygetAggregate(Set includedAggregationNames, Set
clearedAggregationNames)
Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames) throws DTraceException
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).
includedAggregationNames
- if null
, all available
aggregations are included; if non-null, only those aggregations
specifically named by the given set are included
java.lang.IllegalStateException
- if called before go()
or
after close()
DTraceException
- if an exception occurs in the native
DTrace librarygetAggregate(Set includedAggregationNames, Set
clearedAggregationNames)
Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames, java.util.Set<java.lang.String> clearedAggregationNames) throws DTraceException
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.
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
java.lang.IllegalStateException
- if called before go()
or
after close()
DTraceException
- if an exception occurs in the native
DTrace libraryint createProcess(java.lang.String command) throws DTraceException
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.
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.
java.lang.NullPointerException
- if the given command is nul
l
java.lang.IllegalArgumentException
- if the given command is empty or
contains only whitespace
java.lang.IllegalStateException
- if called before open()
or after go()
,
or if the consumer is closed
DTraceException
- if the process cannot be createdgrabProcess(int pid)
void grabProcess(int pid) throws DTraceException
$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.
pid
- process ID of the process to be grabbed
java.lang.IllegalStateException
- if called before open()
or after go()
,
or if the consumer is closed
DTraceException
- if the process cannot be grabbedcreateProcess(String command)
java.util.List<ProbeDescription> listProbes(ProbeDescription filter) throws DTraceException
ProbeDescription
for information about pattern syntax and
wildcarding.
filter
- use ProbeDescription.EMPTY
to get all
probes, otherwise get only those probes that match the given
filter
java.lang.IllegalStateException
- if called before open()
or after go()
,
or if the consumer is closed
DTraceException
- if an exception occurs in the native
DTrace libraryopen(OpenFlag[] flags)
,
close()
,
listProbeDetail(ProbeDescription filter)
,
listProgramProbes(Program program)
java.util.List<Probe> listProbeDetail(ProbeDescription filter) throws DTraceException
filter
- use ProbeDescription.EMPTY
to get all
probes, otherwise get only those probes that match the given
filter
java.lang.IllegalStateException
- if called before open()
or after go()
,
or if the consumer is closed
DTraceException
- if an exception occurs in the native
DTrace librarylistProbes(ProbeDescription filter)
,
listProgramProbeDetail(Program program)
java.util.List<ProbeDescription> listProgramProbes(Program program) throws DTraceException
program
- a Program
identifier returned by compile(String
program, ...)
or compile(File program, ...)
java.lang.NullPointerException
- if the given program identifier is
null
java.lang.IllegalArgumentException
- if the specified program was not
compiled by this consumer
java.lang.IllegalStateException
- if called before open()
or after go()
,
or if the consumer is closed
DTraceException
- if an exception occurs in the native
DTrace librarylistProbes(ProbeDescription filter)
java.util.List<Probe> listProgramProbeDetail(Program program) throws DTraceException
program
- a Program
identifier returned by compile(String
program, ...)
or compile(File program, ...)
java.lang.NullPointerException
- if the given program identifier is
null
java.lang.IllegalArgumentException
- if the specified program was not
compiled by this consumer
java.lang.IllegalStateException
- if called before open()
or after go()
,
or if the consumer is closed
DTraceException
- if an exception occurs in the native
DTrace librarylistProgramProbes(Program program)
,
listProbeDetail(ProbeDescription filter)
java.lang.String lookupKernelFunction(int address)
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.
java.lang.IllegalStateException
- if called before go()
or
after close()
lookupKernelFunction(long address)
java.lang.String lookupKernelFunction(long address)
address
- 64-bit kernel function address
java.lang.IllegalStateException
- if called before go()
or
after close()
lookupKernelFunction(int address)
java.lang.String lookupUserFunction(int pid, int address)
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.
java.lang.IllegalStateException
- if called before go()
or
after close()
lookupUserFunction(int pid, long address)
java.lang.String lookupUserFunction(int pid, long address)
pid
- ID of the user process containing the addressed
functionaddress
- 64-bit user function address
java.lang.IllegalStateException
- if called before go()
or
after close()
lookupUserFunction(int pid, int address)
java.lang.String getVersion()
dtrace(1M)
with the -V
option)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |