fast.html revision fb3fb4f3d76d55b64440afd0af72775dfad3bd1d
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Copyright 2006 Sun Microsystems, Inc. All rights reserved.
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Use is subject to license terms.
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync ident "%Z%%M% %I% %E% SMI"
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync CDDL HEADER START
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync The contents of this file are subject to the terms of the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Common Development and Distribution License (the "License").
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync You may not use this file except in compliance with the License.
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync See the License for the specific language governing permissions
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync and limitations under the License.
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync When distributing Covered Code, include this CDDL HEADER in each
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync file and include the License file at usr/src/OPENSOLARIS.LICENSE.
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync If applicable, add the following below this CDDL HEADER, with the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync fields enclosed by brackets "[]" replaced with your own identifying
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync information: Portions Copyright [yyyy] [name of copyright owner]
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync CDDL HEADER END
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync <title>Quick Start Guide to the Java DTrace API</title>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<h1><a name="Quick_Start_Guide_to_the_Java_DTrace_API_"></a>Quick Start
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<h1><small><small>to the</small> Java DTrace API</small></h1>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync <li><a href="#Hello_World">"hello, world" Example</a></li>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync <li><a href="#Writing_a_Simple_Consumer">Writing a Simple Consumer</a></li>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync <li><a href="#Running_hello.d_Script">Running the <tt>hello.d</tt>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync <li><a href="#Target_Process">Target Process ID</a></li>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync <li><a href="#Closing_Consumers">Closing Consumers</a></li>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync <li><a href="#Learning_DTrace">Learning More</a><br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<h2><a name="Hello_World"></a>"hello, world" Example</h2>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncTo demonstrate how to use the Java DTrace API, let's write a simple Java
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncprogram that runs a D script, in this case <tt>hello.d</tt> (prints
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync"hello, world" and exits). You will need root permission to use the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncJava DTrace API (just as you do to use the <tt>dtrace(1M)</tt> command).
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncYou may want to eliminate this inconvenience by adding the following
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt><i>user-name</i>::::defaultpriv=basic,dtrace_kernel,dtrace_proc</tt>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidln0?a=view>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>Security</b></a> chapter of the <i>Solaris Dynamic Tracing Guide</i>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncfor more information.
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<h4><a name="Writing_a_Simple_Consumer"></a>Writing a Simple Consumer</h4>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncCreating a DTrace <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/Consumer.html">consumer</a>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Consumer consumer = new LocalConsumer();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncBefore you can do anything with the consumer, you must first open it.
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThen you simply compile and enable one or more D programs and run it:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync consumer.go(); // runs in a background thread
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncTo get the data generated by DTrace, you also need to add a <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/ConsumerListener.html">listener</a>:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync consumer.addConsumerListener(new ConsumerAdapter() {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync public void dataReceived(DataEvent e) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncHere is a simple example that runs a given D script:<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>Java program (<a href="/examples/TestAPI.java">TestAPI.java</a>)</b>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync public class TestAPI {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync public static void
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync main(String[] args)
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync if (args.length < 1) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync System.err.println("Usage: java TestAPI <script> [ macroargs... ]");
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync File file = new File(args[0]);
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync String[] macroArgs = new String[args.length - 1];
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync System.arraycopy(args, 1, macroArgs, 0, (args.length - 1));</font>
1e0b63f46b392446985612eb6fde60005e69414avboxsync Consumer consumer = new LocalConsumer();
1e0b63f46b392446985612eb6fde60005e69414avboxsync consumer.addConsumerListener(new ConsumerAdapter() {
1e0b63f46b392446985612eb6fde60005e69414avboxsync public void dataReceived(DataEvent e) {
1e0b63f46b392446985612eb6fde60005e69414avboxsync try {</font>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync consumer.compile(file, macroArgs);
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync } catch (Exception e) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncCompile the test program as follows:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<h4><a name="Running_hello.d_Script"></a>Running the <tt>hello.d</tt> Script</h4>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncNow we need a D script for the program to run. The following is a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncsimple example that prints "hello, world" and exits:<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>D script (<a href="/examples/hello.d">hello.d</a>)</b>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync dtrace:::BEGIN
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync trace("hello, world");
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncRun as follows:<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncOn sparc you need to add the <tt>-d64</tt> option to java:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync java -d64 -cp .:dtrace.jar TestAPI hello.d</span><br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncYou may need to set <tt>LD_LIBRARY_PATH</tt> so that Java can find
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>libdtrace_jni.so</tt> on your system. The output should look like
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync org.opensolaris.os.dtrace.ProbeData[epid = 1, cpu = 1,
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync enabledProbeDescription = dtrace:::BEGIN, flow = null, records =
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync ["hello, world", 0]]
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThere is one record in the <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/ProbeData.html"><tt>ProbeData</tt></a>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncfor each action in the D script. The first record is generated by the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>trace()</tt> action. The second is generated by the <tt>exit()</tt>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncaction. For prettier output, you could change the <tt>ConsumerAdapter <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync href="/api/org/opensolaris/os/dtrace/ConsumerAdapter.html#dataReceived%28org.opensolaris.os.dtrace.DataEvent%29">dataReceived()</a></tt>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncimplementation as follows:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync consumer.addConsumerListener(new ConsumerAdapter() {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync public void dataReceived(DataEvent e) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync ProbeData data = e.getProbeData();
b7586b9fa1110d4f7b9bbe53e691ca71b376cb34vboxsync java.util.List < Record > records = data.getRecords();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync for (Record r : records) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync if (r instanceof ExitRecord) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThe example Java program can just as easily run a more complex script,
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncsuch as an aggregation:<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>D script (<a href="/examples/syscall.d">syscall.d</a>)</b>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync syscall:::entry
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync / execname == $$1 /
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync @[probefunc] = count();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync profile:::tick-1sec
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThe above script uses the <tt>$$1</tt> macro variable as a placeholder
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncfor whatever executable you'd like to trace. See the <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidliq?a=view><b>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncMacro Arguments</b></a> section of the <b>Scripting</b> chapter of the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<i>Solaris Dynamic Tracing Guide</i>. Using two dollar signs (<tt>$$1</tt>)
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncinstead of one (<tt>$1</tt>) forces expansion of the macro variable to
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynctype string.<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncTo run the example Java program using the above D script, you need to
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncspecify an argument to the <tt>execname</tt> placeholder. To be sure of
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncgetting output, let's use "java":<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncA data record generated by the <tt>printa()</tt> action is printed to
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncthe console once every second. It contains counts of system calls by
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncfunction name made by java. No record is generated by the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncIf you omit the argument to the <tt>execname</tt> placeholder, the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncprogram fails to compile and the API throws the following exception:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync org.opensolaris.os.dtrace.DTraceException: failed to compile script
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync syscall.d: line 2: macro argument $$1 is not defined
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync at org.opensolaris.os.dtrace.LocalConsumer._compileFile(Native Method)
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync at org.opensolaris.os.dtrace.LocalConsumer.compile(LocalConsumer.java:342)
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncA DTrace script may have more than one aggregation. In that case, each
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncaggregation needs a distinct name:<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>D script (<a href="/examples/intrstat.d">intrstat.d</a>)</b>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync sdt:::interrupt-start
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync self->ts = vtimestamp;
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync sdt:::interrupt-complete
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync / self->ts && arg0 /
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync this->devi = (struct dev_info *)arg0;
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync @counts[stringof(`devnamesp[this->devi->devi_major].dn_name),
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync this->devi->devi_instance, cpu] = count();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync @times[stringof(`devnamesp[this->devi->devi_major].dn_name),
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync this->devi->devi_instance, cpu] = sum(vtimestamp - self->ts);
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync self->ts = 0;
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThe <tt>@counts</tt> and <tt>@times</tt> aggregations both accumulate
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncvalues for each unique combination of device name, device instance, and
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncCPU (a three-element tuple). In this example we drop the <tt>tick</tt>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncprobe to demonstrate a more convenient way to get aggregation data
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncwithout the use of the <tt>printa()</tt> action. The <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/Consumer.html#getAggregate%28%29">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>getAggregate()</tt></a> method allows us to get all aggregations at
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynconce on a programmatic interval.<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>Java program (<a href="/examples/TestAPI2.java">TestAPI2.java</a>)</b>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync consumer.compile(file, macroArgs);
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Aggregate a;
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Thread.sleep(1000); // 1 second
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync if (!a.asMap().isEmpty()) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync } while (consumer.isRunning());<font color=#aaaaaa>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync } catch (Exception e) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncCompile and run:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncTry removing the <tt>tick</tt> probe from the <tt>syscall.d</tt> example
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncand running it again with the above modification (<tt>TestAPI2</tt>).<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncBy default, the requested aggregate includes every aggregation and
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncaccumulates running totals. To display values per time interval
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync(instead of running totals), clear the aggregations each time you call
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>getAggregate()</tt>. Clearing an aggregation resets all counts to
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynczero without removing any tuples. The following modification to the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncexample above clears all aggregations:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync a = consumer.getAggregate(null, null); // included, cleared
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncEach <tt>Set</tt> of aggregation names, <tt>included</tt> and
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>cleared</tt>, specifies <i>all</i> aggregations if <tt>null</tt> and
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncno aggregations if empty. Any subset is possible. However, if an
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncaggregation has ever been used in the <tt>printa()</tt> action, it is no
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynclonger available to the <tt>getAggregate()</tt> method.<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncBe aware that you cannot call <tt>getAggregate()</tt> on an interval
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncfaster that the <tt>aggrate</tt> setting. See the <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlis?a=view>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>Options and Tunables</b></a> chapter of the <i>Solaris Dynamic
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhf?a=view>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>Minimizing Drops</b></a> section of the <b>Aggregations</b> chapter
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncfor specific information about the <tt>aggrate</tt> option. The default
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>aggrate</tt> is once per second. Here's an example of how you might
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync consumer.setOption(Option.aggrate, Option.millis(500)); // every half second
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncEven a single drop terminates the consumer unless you override the <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/ConsumerAdapter.html#dataDropped%28org.opensolaris.os.dtrace.DropEvent%29">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>dataDropped()</tt></a> method of <tt>ConsumerAdapter</tt> to handle
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncdrops differently. To avoid drops, it is probably better to increase
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncthe <tt>aggsize</tt> option, since increasing the <tt>aggrate</tt> makes
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncthe consumer work harder. In most cases, the <tt>aggrate</tt> should
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynconly be increased when you need to update a display of aggregation data
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncmore frequently than once per second. Many runtime options, including
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>aggrate</tt>, can be changed dynamically while the consumer is
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncrunning.<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncIt's also worth mentioning that a D aggregation may omit square
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncbrackets and aggregate only a single value:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync @total = count();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThe resulting singleton <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/Aggregation.html">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>Aggregation</tt></a> instance has one record that may be obtained as
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Aggregate a = consumer.getAggregate();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Aggregation total = a.getAggregation("total");
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync AggregationRecord totalRecord = total.getRecord(Tuple.EMPTY);
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<h2><a name="Target_Process"></a>Target Process ID</h2>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncIn addition to supporting macro arguments (see the <tt>syscall.d</tt>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncaggregation example above), the Java DTrace API also supports the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlir?a=view>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>Target Process ID</b></a> section of the <b>Scripting</b> chapter of
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncthe <i>Solaris Dynamic Tracing Guide</i>.) This allows you to trace a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncprocess from the very beginning of its execution, rather than sometime
b7586b9fa1110d4f7b9bbe53e691ca71b376cb34vboxsyncafter you manually obtain its process ID. The API does this by creating
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynca process that is initially suspended and allowed to start only after <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/Consumer.html#go%28%29">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>go()</tt></a> has initiated tracing. For example, we might want to
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncaggregate all the system calls from start to finish made by the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>D script (<a href="/examples/target.d">target.d</a>)</b>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync syscall:::entry
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync / pid == $target /
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync @[probefunc] = count();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncA modified version of the <tt>TestAPI.java</tt> program adds the <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/Consumer.html#createProcess%28java.lang.String%29">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>createProcess()</tt></a> call to execute the given command but
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncprevent it from starting until the consumer is running:<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<b>Java program (<a href="/examples/TestTarget.java">TestTarget.java</a>)</b>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync consumer.createProcess(command);<font color=#aaaaaa>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncIt also overrides the <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/ConsumerAdapter.html#processStateChanged%28org.opensolaris.os.dtrace.ProcessEvent%29">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>ConsumerAdapter</tt> to print a notification when the process has
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync consumer.addConsumerListener(new ConsumerAdapter() {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync public void dataReceived(DataEvent e) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync public void consumerStopped(ConsumerEvent e) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Aggregate a = consumer.getAggregate();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync for (Aggregation agg : a.asMap().values()) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync for (AggregationRecord rec : agg.asMap().values()) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync } catch (Exception x) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync public void processStateChanged(ProcessEvent e) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncCompile and run:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync java -d64 -cp .:dtrace.jar TestTarget target.d date
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThe consumer exits automatically when the target <tt>date</tt> process
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynccompletes.<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<h2><a name="Closing_Consumers"></a>Closing Consumers</h2>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncAn application using the Java DTrace API may run multiple consumers
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncsimultaneously. When a consumer stops running, the programmer is
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncresponsible for closing it in order to release the system resources it
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncholds. A consumer may stop running for any of the following reasons:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref=/api/org/opensolaris/os/dtrace/Consumer.html#stop()>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync <li>Its <tt>$target</tt> process or processes (if any) all completed</li>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncBy default, an exception prints a stack trace to <tt>stderr</tt> before
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncnotifying listeners that the consumer has stopped. You can define
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncdifferent behavior by setting an <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref=/api/org/opensolaris/os/dtrace/ExceptionHandler.html>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>ExceptionHandler</tt></a>, but the consumer is still stopped.<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThe same listener that receives probe data generated by DTrace is also
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncnotified when the consumer stops. This is a good place to close the
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync consumer.addConsumerListener(new ConsumerAdapter() {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync public void dataReceived(DataEvent e) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync public void consumerStopped(ConsumerEvent e) {
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Consumer consumer = (Consumer)e.getSource();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThis releases the resources held by the consumer in all cases, i.e.
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncafter it exits for <i>any</i> of the reasons listed above.<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncYou can request the last aggregate snapshot made by a stopped consumer,
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncas long as it has not yet been closed:
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync Aggregate a = consumer.getAggregate();
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncNote however that any aggregation that has already appeared in a <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref=/api/org/opensolaris/os/dtrace/PrintaRecord.html>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<tt>PrintaRecord</tt></a> as a result of the <tt>printa()</tt> action
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncaction will not be included in the requested aggregate.
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<h2><a name="Learning_DTrace"></a>Learning More</h2>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncThe <a href="http://www.opensolaris.org/os/community/dtrace/">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncOpenSolaris DTrace page</a> has links to resources to help you learn
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncDTrace. In particular, you should read the <a
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="http://docs.sun.com/db/doc/817-6223"><i>Solaris Dynamic Tracing
3d5847db3882b6af81db232f55ee404b22141e5dvboxsyncTry the example Java programs on this page with other D scripts. You
3d5847db3882b6af81db232f55ee404b22141e5dvboxsyncneed not remove <tt>#!/usr/sbin/dtrace -s</tt> from the top of an
3d5847db3882b6af81db232f55ee404b22141e5dvboxsyncexecutable script. You may want to remove <tt>profile:::tick*</tt>
3d5847db3882b6af81db232f55ee404b22141e5dvboxsynchref="/api/org/opensolaris/os/dtrace/Consumer.html#getAggregate%28%29">
3d5847db3882b6af81db232f55ee404b22141e5dvboxsync<tt>getAggregate()</tt></a> method and control the aggregating interval
3d5847db3882b6af81db232f55ee404b22141e5dvboxsyncprogrammatically. If the script uses the pre-compiler, you will need to
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/Consumer.html#setOption%28java.lang.String%29">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsynchref="/api/org/opensolaris/os/dtrace/Option.html#cpp">
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncTo quickly familiarize yourself with the Java DTrace API, take a look at
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsyncthe overview <a href="JavaDTraceAPI.html">diagram</a>.<br>
9055f61bb57d2a625c6434d55beac7565c3b3c0dvboxsync<a href="#Quick_Start_Guide_to_the_Java_DTrace_API_">Back to top</a><br>