org.opensolaris.os.dtrace
Interface Consumer

All Known Implementing Classes:
LocalConsumer

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.

See Also:
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

open

void open(Consumer.OpenFlag... flags)
          throws DTraceException
Opens this DTrace consumer. Optional flags indicate behaviors that can only be set at the time of opening. Most optional behaviors are set using 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.

Throws:
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 library
See Also:
compile(File program, String[] macroArgs), compile(String program, String[] macroArgs), enable(), go()

compile

Program compile(java.lang.String program,
                java.lang.String... macroArgs)
                throws DTraceException
Compiles the given D program string. Optional macro arguments replace corresponding numbered macro variables in the D program starting at $1.

Parameters:
program - program string
macroArgs - 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.
Returns:
a non-null Program identifier that may be passed to enable()
Throws:
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 library
See Also:
compile(File program, String[] macroArgs)

compile

Program compile(java.io.File program,
                java.lang.String... macroArgs)
                throws DTraceException,
                       java.io.IOException,
                       java.lang.SecurityException
Compiles the given D program file. Optional macro arguments replace corresponding numbered macro variables in the D program starting at $1.

Parameters:
program - program file
macroArgs - 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.
Returns:
a non-null Program identifier that may be passed to enable()
Throws:
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 file
See Also:
compile(String program, String[] macroArgs)

enable

void enable()
            throws DTraceException
Enables all DTrace probes compiled by this consumer. Call 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.

Throws:
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 library
See Also:
enable(Program program)

enable

void enable(Program program)
            throws DTraceException
Enables DTrace probes matching the given program and attaches information about those probes to the given program. A probe matched multiple times (within the same D program or in multiple D programs) triggers the actions associated with each matching occurrence every time that probe fires.

Parameters:
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.
Throws:
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 library
See Also:
compile(String program, String[] macroArgs), compile(File program, String[] macroArgs), enable(), getProgramInfo(Program program)

getProgramInfo

void getProgramInfo(Program program)
                    throws DTraceException
Attaches information about matching DTrace probes to the given program. Attaches the same information to the given program as that attached by enable(Program program) but without enabling the probes.

Throws:
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 library
See Also:
compile(String program, String[] macroArgs), compile(File program, String[] macroArgs), enable(Program program)

setOption

void setOption(java.lang.String option)
               throws DTraceException
Sets a boolean option.

Throws:
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)
See Also:
setOption(String option, String value), unsetOption(String option)

unsetOption

void unsetOption(java.lang.String option)
                 throws DTraceException
Unsets a boolean option.

Throws:
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)
See Also:
setOption(String option)

setOption

void setOption(java.lang.String option,
               java.lang.String value)
               throws DTraceException
Sets the value of a DTrace option. If the given option affects compile-time behavior, it must be set before calling 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.

Throws:
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:
  • The option is invalid
  • The value is invalid for the given option
  • 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)
See Also:
open(OpenFlag[] flags), getOption(String option), Option

getOption

long getOption(java.lang.String option)
               throws DTraceException
Gets the value of a DTrace option.

Returns:
the value of the given DTrace option: If the given option is a boolean option and is currently unset, the returned value is 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.
Throws:
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 invalid
See Also:
setOption(String option), unsetOption(String option), setOption(String option, String value), Option

isOpen

boolean isOpen()
Reports whether or not this consumer is open.

Returns:
true if and only if open() has been called on this consumer and close() has not

isEnabled

boolean isEnabled()
Reports whether or not it is valid to call go().

Returns:
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 called

isRunning

boolean isRunning()
Reports whether or not this consumer is running. There may be a delay after calling go() before this consumer actually starts running (listeners are notified by the consumerStarted() method).

Returns:
true if this consumer is running, false otherwise

isClosed

boolean isClosed()
Reports whether or not this consumer is closed. A closed consumer cannot be reopened.

Note that a closed consumer is different from a consumer that has not yet been opened.

Returns:
true if close() has been called on this consumer, false otherwise

go

void go()
        throws DTraceException
Begin tracing and start a background thread to consume generated probe data.

Throws:
java.lang.IllegalStateException - if not isEnabled()
DTraceException - if an exception occurs in the native DTrace library
See Also:
go(ExceptionHandler h), open(OpenFlag[] flags), compile(String program, String[] macroArgs), compile(File program, String[] macroArgs), enable(), stop(), close()

go

void go(ExceptionHandler h)
        throws DTraceException
Begin tracing and start a background thread to consume generated probe data. Handle any exception thrown in the consumer thread with the given handler.

Throws:
java.lang.IllegalStateException - if not isEnabled()
DTraceException - if an exception occurs in the native DTrace library
See Also:
go()

stop

void stop()
Stops all tracing, as well as the background thread started by 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).

Throws:
java.lang.IllegalStateException - if called before go() or if stop() was already called
See Also:
go(), abort(), close()

abort

void abort()
Aborts the background thread started by 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.

See Also:
stop()

close

void close()
Closes an open consumer and releases the system resources it was holding. If the consumer is running, 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.

See Also:
open(OpenFlag[] flags)

addConsumerListener

void addConsumerListener(ConsumerListener l)
Adds a listener for probe data generated by this consumer.


removeConsumerListener

void removeConsumerListener(ConsumerListener l)
Removes a listener for probe data generated by this consumer.


getAggregate

Aggregate getAggregate()
                       throws DTraceException
Gets a snapshot of all aggregations except those that have already been captured in a 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).

Throws:
java.lang.IllegalStateException - if called before go() or after close()
DTraceException - if an exception occurs in the native DTrace library
See Also:
getAggregate(Set includedAggregationNames, Set clearedAggregationNames)

getAggregate

Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames)
                       throws DTraceException
Gets a snapshot of all the specified aggregations except those that have already been captured in a 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).

Parameters:
includedAggregationNames - if null, all available aggregations are included; if non-null, only those aggregations specifically named by the given set are included
Throws:
java.lang.IllegalStateException - if called before go() or after close()
DTraceException - if an exception occurs in the native DTrace library
See Also:
getAggregate(Set includedAggregationNames, Set clearedAggregationNames)

getAggregate

Aggregate getAggregate(java.util.Set<java.lang.String> includedAggregationNames,
                       java.util.Set<java.lang.String> clearedAggregationNames)
                       throws DTraceException
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. 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.

Parameters:
includedAggregationNames - if null, all available aggregations are included; if non-null, only those aggregations specifically named by the given set are included
clearedAggregationNames - if null, all available aggregations are cleared; if non-null, only those aggregations specifically named by the given set are cleared
Throws:
java.lang.IllegalStateException - if called before go() or after close()
DTraceException - if an exception occurs in the native DTrace library

createProcess

int createProcess(java.lang.String command)
                  throws DTraceException
Creates a process by executing the given command on the system and returns the created process ID. The created process is suspended until calling 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.

Parameters:
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.
Returns:
ID of the created process (pid)
Throws:
java.lang.NullPointerException - if the given command is null
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 created
See Also:
grabProcess(int pid)

grabProcess

void grabProcess(int pid)
                 throws DTraceException
Grabs the specified process and caches its symbol tables. The macro variable $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.

Parameters:
pid - process ID of the process to be grabbed
Throws:
java.lang.IllegalStateException - if called before open() or after go(), or if the consumer is closed
DTraceException - if the process cannot be grabbed
See Also:
createProcess(String command)

listProbes

java.util.List<ProbeDescription> listProbes(ProbeDescription filter)
                                            throws DTraceException
Lists probes that match the given probe description. See ProbeDescription for information about pattern syntax and wildcarding.

Parameters:
filter - use ProbeDescription.EMPTY to get all probes, otherwise get only those probes that match the given filter
Returns:
a non-null list of probe descriptions
Throws:
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
See Also:
open(OpenFlag[] flags), close(), listProbeDetail(ProbeDescription filter), listProgramProbes(Program program)

listProbeDetail

java.util.List<Probe> listProbeDetail(ProbeDescription filter)
                                      throws DTraceException
Lists probes that match the given probe description and includes detail such as stability information about each listed probe.

Parameters:
filter - use ProbeDescription.EMPTY to get all probes, otherwise get only those probes that match the given filter
Returns:
a non-null list of probe detail
Throws:
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
See Also:
listProbes(ProbeDescription filter), listProgramProbeDetail(Program program)

listProgramProbes

java.util.List<ProbeDescription> listProgramProbes(Program program)
                                                   throws DTraceException
Lists probes that match the given compiled program. A probe matches a D program if that program contains any matching probe description.

Parameters:
program - a Program identifier returned by compile(String program, ...) or compile(File program, ...)
Returns:
a non-null list of probe descriptions
Throws:
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 library
See Also:
listProbes(ProbeDescription filter)

listProgramProbeDetail

java.util.List<Probe> listProgramProbeDetail(Program program)
                                             throws DTraceException
Lists probes that match the given compiled program and includes detail such as stability information about each listed probe.

Parameters:
program - a Program identifier returned by compile(String program, ...) or compile(File program, ...)
Returns:
a non-null list of probe detail
Throws:
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 library
See Also:
listProgramProbes(Program program), listProbeDetail(ProbeDescription filter)

lookupKernelFunction

java.lang.String lookupKernelFunction(int address)
Gets the kernel function name for the given 32-bit kernel address.

Parameters:
address - 32-bit kernel function address, such as the value of a Tuple member in an AggregationRecord to be converted for display
Returns:
the result of kernel function lookup as one of the following:
  • module`function
  • module`function+offset
  • module`address
  • address
where 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.
Throws:
java.lang.IllegalStateException - if called before go() or after close()
See Also:
lookupKernelFunction(long address)

lookupKernelFunction

java.lang.String lookupKernelFunction(long address)
Gets the kernel function name for the given 64-bit kernel address.

Parameters:
address - 64-bit kernel function address
Returns:
kernel function name
Throws:
java.lang.IllegalStateException - if called before go() or after close()
See Also:
lookupKernelFunction(int address)

lookupUserFunction

java.lang.String lookupUserFunction(int pid,
                                    int address)
Gets the user function name for the given 32-bit user address and process ID.

Parameters:
pid - ID of the user process containing the addressed function
address - 32-bit user function address, such as the value of a Tuple member in an AggregationRecord to be converted for display.
Returns:
result of user function lookup as one of the following:
  • module`function
  • module`function+offset
  • module`address
  • address
where 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.
Throws:
java.lang.IllegalStateException - if called before go() or after close()
See Also:
lookupUserFunction(int pid, long address)

lookupUserFunction

java.lang.String lookupUserFunction(int pid,
                                    long address)
Gets the user function name for the given 64-bit user address and process ID.

Parameters:
pid - ID of the user process containing the addressed function
address - 64-bit user function address
Returns:
user function name
Throws:
java.lang.IllegalStateException - if called before go() or after close()
See Also:
lookupUserFunction(int pid, int address)

getVersion

java.lang.String getVersion()
Gets the version of the native DTrace library.

Returns:
version string generated by the native DTrace library (same as the output of dtrace(1M) with the -V option)