91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee Copyright 2007 Sun Microsystems, Inc. All rights reserved.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Use is subject to license terms.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee ident "%Z%%M% %I% %E% SMI"
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee CDDL HEADER START
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee The contents of this file are subject to the terms of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Common Development and Distribution License (the "License").
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee You may not use this file except in compliance with the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee See the License for the specific language governing permissions
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee and limitations under the License.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee When distributing Covered Code, include this CDDL HEADER in each
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee file and include the License file at usr/src/OPENSOLARIS.LICENSE.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee If applicable, add the following below this CDDL HEADER, with the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee fields enclosed by brackets "[]" replaced with your own identifying
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee information: Portions Copyright [yyyy] [name of copyright owner]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee CDDL HEADER END
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee <title>Quick Start Guide to the Java DTrace API</title>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<h1><a name="Quick_Start_Guide_to_the_Java_DTrace_API_"></a>Quick Start
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<h1><small><small>to the</small> Java DTrace API</small></h1>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee <li><a href="#Hello_World">"hello, world" Example</a></li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee <li><a href="#Writing_a_Simple_Consumer">Writing a Simple Consumer</a></li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee <li><a href="#Running_hello.d_Script">Running the <tt>hello.d</tt>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee <li><a href="#Target_Process">Target Process ID</a></li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee <li><a href="#Closing_Consumers">Closing Consumers</a></li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<h2><a name="Hello_World"></a>"hello, world" Example</h2>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeTo demonstrate how to use the Java DTrace API, let's write a simple Java
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeprogram that runs a D script, in this case <tt>hello.d</tt> (prints
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee"hello, world" and exits). You will need root permission to use the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeJava DTrace API (just as you do to use the <tt>dtrace(1M)</tt> command).
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeYou may want to eliminate this inconvenience by adding the following
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt><i>user-name</i>::::defaultpriv=basic,dtrace_kernel,dtrace_proc</tt>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidln0?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>Security</b></a> chapter of the <i>Solaris Dynamic Tracing Guide</i>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeefor more information.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<h4><a name="Writing_a_Simple_Consumer"></a>Writing a Simple Consumer</h4>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeCreating a DTrace <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/Consumer.html">consumer</a>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Consumer consumer = new LocalConsumer();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeBefore you can do anything with the consumer, you must first open it.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThen you simply compile and enable one or more D programs and run it:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee consumer.go(); // runs in a background thread
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeTo get the data generated by DTrace, you also need to add a <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/ConsumerListener.html">listener</a>:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee consumer.addConsumerListener(new ConsumerAdapter() {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void dataReceived(DataEvent e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeHere is a simple example that runs a given D script:<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>Java program (<a href="/examples/TestAPI.java">TestAPI.java</a>)</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public class TestAPI {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public static void
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee main(String[] args)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee if (args.length < 1) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee System.err.println("Usage: java TestAPI <script> [ macroargs... ]");
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee File file = new File(args[0]);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee String[] macroArgs = new String[args.length - 1];
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee System.arraycopy(args, 1, macroArgs, 0, (args.length - 1));</font>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Consumer consumer = new LocalConsumer();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee consumer.addConsumerListener(new ConsumerAdapter() {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void dataReceived(DataEvent e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee try {</font>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee consumer.compile(file, macroArgs);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee } catch (Exception e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeCompile the test program as follows:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<h4><a name="Running_hello.d_Script"></a>Running the <tt>hello.d</tt> Script</h4>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeNow we need a D script for the program to run. The following is a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeesimple example that prints "hello, world" and exits:<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>D script (<a href="/examples/hello.d">hello.d</a>)</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee dtrace:::BEGIN
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee trace("hello, world");
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeRun as follows:<br>
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee java -cp .:/usr/share/lib/java/dtrace.jar TestAPI hello.d
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomeeThe output should look like this:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee org.opensolaris.os.dtrace.ProbeData[epid = 1, cpu = 1,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee enabledProbeDescription = dtrace:::BEGIN, flow = null, records =
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee ["hello, world", 0]]
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThere is one record in the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/ProbeData.html"><tt>ProbeData</tt></a>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeefor each action in the D script. The first record is generated by the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>trace()</tt> action. The second is generated by the <tt>exit()</tt>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeaction. For prettier output, you could change the <tt>ConsumerAdapter <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee href="/api/org/opensolaris/os/dtrace/ConsumerAdapter.html#dataReceived%28org.opensolaris.os.dtrace.DataEvent%29">dataReceived()</a></tt>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeimplementation as follows:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee consumer.addConsumerListener(new ConsumerAdapter() {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void dataReceived(DataEvent e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee ProbeData data = e.getProbeData();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee java.util.List < Record > records = data.getRecords();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee for (Record r : records) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee if (r instanceof ExitRecord) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThe example Java program can just as easily run a more complex script,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeesuch as an aggregation:<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>D script (<a href="/examples/syscall.d">syscall.d</a>)</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee syscall:::entry
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee / execname == $$1 /
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee @[probefunc] = count();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee profile:::tick-1sec
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThe above script uses the <tt>$$1</tt> macro variable as a placeholder
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeefor whatever executable you'd like to trace. See the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidliq?a=view><b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeMacro Arguments</b></a> section of the <b>Scripting</b> chapter of the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<i>Solaris Dynamic Tracing Guide</i>. Using two dollar signs (<tt>$$1</tt>)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeinstead of one (<tt>$1</tt>) forces expansion of the macro variable to
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeetype string.<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeTo run the example Java program using the above D script, you need to
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomeespecify an argument to the <tt>execname</tt> placeholder, such as
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee java -cp .:/usr/share/lib/java/dtrace.jar TestAPI syscall.d java
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeA data record generated by the <tt>printa()</tt> action is printed to
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeethe console once every second. It contains counts of system calls by
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeefunction name made by java. No record is generated by the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeIf you omit the argument to the <tt>execname</tt> placeholder, the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeprogram fails to compile and the API throws the following exception:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee org.opensolaris.os.dtrace.DTraceException: failed to compile script
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee syscall.d: line 2: macro argument $$1 is not defined
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee at org.opensolaris.os.dtrace.LocalConsumer._compileFile(Native Method)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee at org.opensolaris.os.dtrace.LocalConsumer.compile(LocalConsumer.java:342)
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeA DTrace script may have more than one aggregation. In that case, each
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeaggregation needs a distinct name:<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>D script (<a href="/examples/intrstat.d">intrstat.d</a>)</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee sdt:::interrupt-start
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee self->ts = vtimestamp;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee sdt:::interrupt-complete
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee / self->ts && arg0 /
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee this->devi = (struct dev_info *)arg0;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee @counts[stringof(`devnamesp[this->devi->devi_major].dn_name),
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee this->devi->devi_instance, cpu] = count();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee @times[stringof(`devnamesp[this->devi->devi_major].dn_name),
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee this->devi->devi_instance, cpu] = sum(vtimestamp - self->ts);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee self->ts = 0;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThe <tt>@counts</tt> and <tt>@times</tt> aggregations both accumulate
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeevalues for each unique combination of device name, device instance, and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeCPU (a three-element tuple). In this example we drop the <tt>tick</tt>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeprobe to demonstrate a more convenient way to get aggregation data
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeewithout the use of the <tt>printa()</tt> action. The <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/Consumer.html#getAggregate%28%29">
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee<tt>getAggregate()</tt></a> method allows us to get a read-consistent
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomeesnapshot of all aggregations at once on a programmatic interval.<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>Java program (<a href="/examples/TestAPI2.java">TestAPI2.java</a>)</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee consumer.compile(file, macroArgs);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Aggregate a;
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Thread.sleep(1000); // 1 second
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee if (!a.asMap().isEmpty()) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee } catch (Exception e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeCompile and run:
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee javac -cp /usr/share/lib/java/dtrace.jar TestAPI2.java
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee java -cp .:/usr/share/lib/java/dtrace.jar TestAPI2 intrstat.d
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeTry removing the <tt>tick</tt> probe from the <tt>syscall.d</tt> example
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeand running it again with the above modification (<tt>TestAPI2</tt>).<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeBy default, the requested aggregate includes every aggregation and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeaccumulates running totals. To display values per time interval
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee(instead of running totals), clear the aggregations each time you call
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>getAggregate()</tt>. Clearing an aggregation resets all counts to
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomeezero without removing any elements. The following modification to the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeexample above clears all aggregations:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee a = consumer.getAggregate(null, null); // included, cleared
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeEach <tt>Set</tt> of aggregation names, <tt>included</tt> and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>cleared</tt>, specifies <i>all</i> aggregations if <tt>null</tt> and
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeno aggregations if empty. Any subset is possible. However, if an
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeaggregation has ever been used in the <tt>printa()</tt> action, it is no
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeelonger available to the <tt>getAggregate()</tt> method.<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeBe aware that you cannot call <tt>getAggregate()</tt> on an interval
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlis?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>Options and Tunables</b></a> chapter of the <i>Solaris Dynamic
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlhf?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>Minimizing Drops</b></a> section of the <b>Aggregations</b> chapter
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeefor specific information about the <tt>aggrate</tt> option. The default
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>aggrate</tt> is once per second. Here's an example of how you might
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee consumer.setOption(Option.aggrate, Option.millis(500)); // every half second
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeEven a single drop terminates the consumer unless you override the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/ConsumerAdapter.html#dataDropped%28org.opensolaris.os.dtrace.DropEvent%29">
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>dataDropped()</tt></a> method of <tt>ConsumerAdapter</tt> to handle
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeedrops differently. To avoid drops, it is probably better to increase
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeethe <tt>aggsize</tt> option, since increasing the <tt>aggrate</tt> makes
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeethe consumer work harder. In most cases, the <tt>aggrate</tt> should
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeonly be increased when you need to update a display of aggregation data
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeemore frequently than once per second. Many runtime options, including
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>aggrate</tt>, can be changed dynamically while the consumer is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeerunning.<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeIt's also worth mentioning that a D aggregation may omit square
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeebrackets and aggregate only a single value:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee @total = count();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThe resulting singleton <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/Aggregation.html">
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee<tt>Aggregation</tt></a> has one record that may be obtained as follows:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Aggregate a = consumer.getAggregate();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Aggregation total = a.getAggregation("total");
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee AggregationRecord totalRecord = total.getRecord(Tuple.EMPTY);
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<h2><a name="Target_Process"></a>Target Process ID</h2>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeIn addition to supporting macro arguments (see the <tt>syscall.d</tt>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeaggregation example above), the Java DTrace API also supports the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref=http://docs.sun.com/app/docs/doc/817-6223/6mlkidlir?a=view>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>Target Process ID</b></a> section of the <b>Scripting</b> chapter of
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeethe <i>Solaris Dynamic Tracing Guide</i>.) This allows you to trace a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeprocess from the very beginning of its execution, rather than sometime
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeafter you manually obtain its process ID. The API does this by creating
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeea process that is initially suspended and allowed to start only after <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/Consumer.html#go%28%29">
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee<tt>go()</tt></a> has initiated tracing. For example, you can aggregate
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomeeall the system calls from start to finish made by the <tt>date</tt>
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomeecommand:<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>D script (<a href="/examples/target.d">target.d</a>)</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee syscall:::entry
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee / pid == $target /
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee @[probefunc] = count();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeA modified version of the <tt>TestAPI.java</tt> program adds the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/Consumer.html#createProcess%28java.lang.String%29">
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>createProcess()</tt></a> call to execute the given command but
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeprevent it from starting until the consumer is running:<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<b>Java program (<a href="/examples/TestTarget.java">TestTarget.java</a>)</b>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeIt also overrides the <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/ConsumerAdapter.html#processStateChanged%28org.opensolaris.os.dtrace.ProcessEvent%29">
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>ConsumerAdapter</tt> to print a notification when the process has
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee consumer.addConsumerListener(new ConsumerAdapter() {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void dataReceived(DataEvent e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void consumerStopped(ConsumerEvent e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Aggregate a = consumer.getAggregate();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee for (Aggregation agg : a.asMap().values()) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee for (AggregationRecord rec : agg.asMap().values()) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee } catch (Exception x) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void processStateChanged(ProcessEvent e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeCompile and run:
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee javac -cp /usr/share/lib/java/dtrace.jar TestTarget.java
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee java -cp .:/usr/share/lib/java/dtrace.jar TestTarget target.d date
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThe consumer exits automatically when the target <tt>date</tt> process
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeecompletes.<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<h2><a name="Closing_Consumers"></a>Closing Consumers</h2>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeAn application using the Java DTrace API may run multiple consumers
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeesimultaneously. When a consumer stops running, the programmer is
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeresponsible for closing it in order to release the system resources it
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeholds. A consumer may stop running for any of the following reasons:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref=/api/org/opensolaris/os/dtrace/Consumer.html#stop()>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee <li>Its <tt>$target</tt> process or processes (if any) all completed</li>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeBy default, an exception prints a stack trace to <tt>stderr</tt> before
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeenotifying listeners that the consumer has stopped. You can define
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeedifferent behavior by setting an <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref=/api/org/opensolaris/os/dtrace/ExceptionHandler.html>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>ExceptionHandler</tt></a>, but the consumer is still stopped.<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThe same listener that receives probe data generated by DTrace is also
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeenotified when the consumer stops. This is a good place to close the
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee consumer.addConsumerListener(new ConsumerAdapter() {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void dataReceived(DataEvent e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee public void consumerStopped(ConsumerEvent e) {
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Consumer consumer = (Consumer)e.getSource();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThis releases the resources held by the consumer in all cases, i.e.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeafter it exits for <i>any</i> of the reasons listed above.<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeYou can request the last aggregate snapshot made by a stopped consumer,
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeas long as it has not yet been closed:
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee Aggregate a = consumer.getAggregate();
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeNote however that any aggregation that has already appeared in a <a
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<tt>PrintaRecord</tt></a> as a result of the <tt>printa()</tt> action
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeaction will not be included in the requested aggregate.
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeThe <a href="http://www.opensolaris.org/os/community/dtrace/">
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeOpenSolaris DTrace page</a> has links to resources to help you learn
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeDTrace. In particular, you should read the <a
127bbe13a6d36580af6a8ded154f1201a6250772tomeehref="http://docs.sun.com/app/docs/doc/817-6223"><i>Solaris Dynamic Tracing
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeTry the example Java programs on this page with other D scripts. You
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeneed not remove <tt>#!/usr/sbin/dtrace -s</tt> from the top of an
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeexecutable script. You may want to remove <tt>profile:::tick*</tt>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/Consumer.html#getAggregate%28%29">
91cfa10a8e55050a5103c4b2e83b0bf8d783a7cbtomee<tt>getAggregate()</tt></a> method and control the data interval
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeprogrammatically. If the script uses the pre-compiler, you will need to
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeehref="/api/org/opensolaris/os/dtrace/Consumer.html#setOption%28java.lang.String%29">
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeeTo quickly familiarize yourself with the Java DTrace API, take a look at
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomeethe overview <a href="JavaDTraceAPI.html">diagram</a>.<br>
fb3fb4f3d76d55b64440afd0af72775dfad3bd1dtomee<a href="#Quick_Start_Guide_to_the_Java_DTrace_API_">Back to top</a><br>