1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License (the "License"). 6 * You may not use this file except in compliance with the License. 7 * 8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 9 * or http://www.opensolaris.org/os/licensing. 10 * See the License for the specific language governing permissions 11 * and limitations under the License. 12 * 13 * When distributing Covered Code, include this CDDL HEADER in each 14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 15 * If applicable, add the following below this CDDL HEADER, with the 16 * fields enclosed by brackets "[]" replaced with your own identifying 17 * information: Portions Copyright [yyyy] [name of copyright owner] 18 * 19 * CDDL HEADER END 20 */ 21 22 /* 23 * Copyright 2006 Sun Microsystems, Inc. All rights reserved. 24 * Use is subject to license terms. 25 */ 26 package org.opensolaris.os.dtrace; 27 28 import java.io.*; 29 import java.util.*; 30 31 /** 32 * Interface to the native DTrace library, each instance is a single 33 * DTrace consumer. To consume the output of DTrace program actions, 34 * {@link #addConsumerListener(ConsumerListener l) register a probe data 35 * listener}. To get a snapshot of all aggregations in a D program on 36 * your own programmatic interval without relying on DTrace actions to 37 * generate that output, use the {@link #getAggregate()} method. 38 * 39 * @see ProbeData 40 * @see Aggregate 41 * 42 * @author Tom Erickson 43 */ 44 public interface Consumer { 45 46 /** 47 * Optional flags passed to {@link #open(Consumer.OpenFlag[] flags) 48 * open()}. 49 */ 50 public enum OpenFlag { 51 /** 52 * Generate 32-bit D programs. {@code ILP32} and {@link 53 * Consumer.OpenFlag#LP64 LP64} are mutually exclusive. 54 */ 55 ILP32, 56 /** 57 * Generate 64-bit D programs. {@code LP64} and {@link 58 * Consumer.OpenFlag#ILP32 ILP32} are mutually exclusive. 59 */ 60 LP64, 61 }; 62 63 /** 64 * Opens this DTrace consumer. Optional flags indicate behaviors 65 * that can only be set at the time of opening. Most optional 66 * behaviors are set using {@link #setOption(String option, String 67 * value) setOption()} after opening the consumer. In the great 68 * majority of cases, the consumer is opened without specifying any 69 * flags: 70 * <pre> {@code consumer.open();}</pre> 71 * Subsequent calls to set options, compile DTrace programs, enable 72 * probes, and run this consumer may be made from any thread. 73 * 74 * @throws NullPointerException if any of the given open flags is 75 * {@code null} 76 * @throws IllegalArgumentException if any of the given flags are 77 * mutually exclusive 78 * @throws IllegalStateException if this consumer is closed or has 79 * already been opened 80 * @throws DTraceException if an exception occurs in the native 81 * DTrace library 82 * @see #compile(File program, String[] macroArgs) 83 * @see #compile(String program, String[] macroArgs) 84 * @see #enable() 85 * @see #go() 86 */ open(OpenFlag .... flags)87 public void open(OpenFlag ... flags) throws DTraceException; 88 89 /** 90 * Compiles the given D program string. Optional macro arguments 91 * replace corresponding numbered macro variables in the D program 92 * starting at {@code $1}. 93 * 94 * @param program program string 95 * @param macroArgs macro substitutions for <i>$n</i> placeholders 96 * embedded in the given D program: {@code macroArgs[0]} replaces 97 * all occurrences of {@code $1}, {@code macroArgs[1]} replaces all 98 * occurrences of {@code $2}, and so on. {@code $0} is 99 * automatically replaced by the executable name and should not be 100 * included in the {@code macroArgs} parameter. See the <a 101 * href=http://dtrace.org/guide/chp-script.html#chp-script-3> 102 * <b>Macro Arguments</b></a> section of the <b>Scripting</b> 103 * chapter of the <i>Dynamic Tracing Guide</i>. 104 * @return a non-null {@code Program} identifier that may be passed 105 * to {@link #enable(Program program) enable()} 106 * @throws NullPointerException if the given program string or any 107 * of the given macro arguments is {@code null} 108 * @throws IllegalStateException if called before {@link 109 * #open(OpenFlag[] flags) open()} or after {@link #go()}, or if the 110 * consumer is closed 111 * @throws DTraceException if an exception occurs in the native 112 * DTrace library 113 * @see #compile(File program, String[] macroArgs) 114 */ compile(String program, String ... macroArgs)115 public Program compile(String program, String ... macroArgs) 116 throws DTraceException; 117 118 /** 119 * Compiles the given D program file. Optional macro arguments 120 * replace corresponding numbered macro variables in the D program 121 * starting at {@code $1}. 122 * 123 * @param program program file 124 * @param macroArgs macro substitutions for <i>$n</i> placeholders 125 * embedded in the given D program: {@code macroArgs[0]} replaces 126 * all occurrences of {@code $1}, {@code macroArgs[1]} replaces all 127 * occurrences of {@code $2}, and so on. {@code $0} is 128 * automatically set to the name of the given file and should not be 129 * included in the {@code macroArgs} parameter. See the <a 130 * href=http://dtrace.org/guide/chp-script.html#chp-script-3> 131 * <b>Macro Arguments</b></a> section of the <b>Scripting</b> 132 * chapter of the <i>Dynamic Tracing Guide</i>. 133 * @return a non-null {@code Program} identifier that may be passed 134 * to {@link #enable(Program program) enable()} 135 * @throws NullPointerException if the given program file or any of 136 * the given macro arguments is {@code null} 137 * @throws IllegalStateException if called before {@link 138 * #open(OpenFlag[] flags) open()} or after {@link #go()}, or if the 139 * consumer is closed 140 * @throws DTraceException if an exception occurs in the native 141 * DTrace library 142 * @throws FileNotFoundException if the given program file cannot be 143 * opened 144 * @throws IOException if an I/O error occurs while reading the 145 * contents of the given program file 146 * @throws SecurityException if a security manager exists and its 147 * {@code checkRead()} method denies read access to the file 148 * @see #compile(String program, String[] macroArgs) 149 */ compile(File program, String ... macroArgs)150 public Program compile(File program, String ... macroArgs) 151 throws DTraceException, IOException, SecurityException; 152 153 /** 154 * Enables all DTrace probes compiled by this consumer. Call {@code 155 * enable()} with no argument to enable everything this consumer has 156 * compiled so far (most commonly a single program, the only one to 157 * be compiled). Call with one {@link Program} at a time if you 158 * need information about enabled probes specific to each program. 159 * 160 * @throws IllegalStateException if called before compiling at least 161 * one program, or if any compiled program is already enabled, or if 162 * {@link #go()} was already called, or if this consumer is closed 163 * @throws DTraceException if an exception occurs in the native 164 * DTrace library 165 * @see #enable(Program program) 166 */ enable()167 public void enable() throws DTraceException; 168 169 /** 170 * Enables DTrace probes matching the given program and attaches 171 * information about those probes to the given program. A probe 172 * matched multiple times (within the same D program or in multiple 173 * D programs) triggers the actions associated with each matching 174 * occurrence every time that probe fires. 175 * 176 * @param program A {@code Program} identifier returned by {@link 177 * #compile(String program, String[] macroArgs) compile(String 178 * program, ...)} or {@link #compile(File program, String[] 179 * macroArgs) compile(File program, ...)}: If the given program is 180 * {@code null}, the call has the same behavior as {@link #enable()} 181 * with no argument; if the given program is non-null, the call 182 * enables only those probes matching that program. In the latter 183 * case, the {@code Program} parameter is modified as a way of 184 * passing back information about the given program and its matching 185 * probes, including program stability. 186 * @throws IllegalArgumentException if the given program is non-null 187 * and not compiled by this {@code Consumer} 188 * @throws IllegalStateException if the given program is already 189 * enabled (or if the given program is {@code null} and <i>any</i> 190 * program is already enabled), or if {@link #go()} was already 191 * called, or if this consumer is closed 192 * @throws DTraceException if an exception occurs in the native 193 * DTrace library 194 * @see #compile(String program, String[] macroArgs) 195 * @see #compile(File program, String[] macroArgs) 196 * @see #enable() 197 * @see #getProgramInfo(Program program) 198 */ enable(Program program)199 public void enable(Program program) throws DTraceException; 200 201 /** 202 * Attaches information about matching DTrace probes to the given 203 * program. Attaches the same information to the given program as 204 * that attached by {@link #enable(Program program)} but without 205 * enabling the probes. 206 * 207 * @throws NullPointerException if the given program is {@code null} 208 * @throws IllegalArgumentException if the given program was not 209 * compiled by this {@code Consumer} 210 * @throws IllegalStateException if called after {@link #close()} 211 * @throws DTraceException if an exception occurs in the native 212 * DTrace library 213 * @see #compile(String program, String[] macroArgs) 214 * @see #compile(File program, String[] macroArgs) 215 * @see #enable(Program program) 216 */ getProgramInfo(Program program)217 public void getProgramInfo(Program program) throws DTraceException; 218 219 /** 220 * Sets a boolean option. 221 * 222 * @throws NullPointerException if the given option is {@code null} 223 * @throws DTraceException if a value is expected for the given 224 * option, or if the option is otherwise invalid 225 * @throws IllegalStateException if called before {@link 226 * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if 227 * the given option is a boolean compile-time option and {@link 228 * #go()} has already been called (see {@link Option} for a 229 * breakdown of runtime and compile-time options) 230 * @see #setOption(String option, String value) 231 * @see #unsetOption(String option) 232 */ setOption(String option)233 public void setOption(String option) throws DTraceException; 234 235 /** 236 * Unsets a boolean option. 237 * 238 * @throws NullPointerException if the given option is {@code null} 239 * @throws DTraceException if the given option is not a boolean 240 * option, or if the option is otherwise invalid 241 * @throws IllegalStateException if called before {@link 242 * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if 243 * the given option is a boolean compile-time option and {@link 244 * #go()} has already been called (see {@link Option} for a 245 * breakdown of runtime and compile-time options) 246 * @see #setOption(String option) 247 */ unsetOption(String option)248 public void unsetOption(String option) throws DTraceException; 249 250 /** 251 * Sets the value of a DTrace option. If the given option affects 252 * compile-time behavior, it must be set before calling {@link 253 * #compile(String program, String[] macroArgs) compile(String 254 * program, ...)} or {@link #compile(File program, String[] 255 * macroArgs) compile(File program, ...)} in order to have an effect 256 * on compilation. Some runtime options including {@link 257 * Option#switchrate switchrate} and {@link Option#aggrate aggrate} 258 * are settable while a consumer is running; others must be set 259 * before calling {@link #go()}. See the <a 260 * href=http://dtrace.org/guide/chp-opt.html#chp-opt> 261 * <b>Options and Tunables</b></a> chapter of the <i>Dynamic Tracing 262 * Guide</i> for information about specific options. 263 * 264 * @throws NullPointerException if the given option or value is 265 * {@code null} 266 * @throws IllegalStateException if called before {@link 267 * #open(OpenFlag[] flags) open()} or after {@link #close()}, or if 268 * the given option is a boolean compile-time option and {@code 269 * go()} has already been called (see {@link Option} for a breakdown 270 * of runtime and compile-time options) 271 * @throws DTraceException for any of the following: 272 * <ul><li>The option is invalid</li> 273 * <li>The value is invalid for the given option</li> 274 * <li>{@code go()} has been called to start this consumer, and the 275 * option is not settable on a running consumer (some runtime 276 * options, including {@link Option#switchrate switchrate} and 277 * {@link Option#aggrate aggrate} are settable while the consumer is 278 * running)</li></ul> 279 * 280 * @see #open(OpenFlag[] flags) 281 * @see #getOption(String option) 282 * @see Option 283 */ setOption(String option, String value)284 public void setOption(String option, String value) throws DTraceException; 285 286 /** 287 * Gets the value of a DTrace option. 288 * 289 * @throws NullPointerException if the given option is {@code null} 290 * @throws IllegalStateException if called before {@link 291 * #open(OpenFlag[] flags) open()} or after {@link #close()} 292 * @throws DTraceException if the given option is invalid 293 * @return the value of the given DTrace option: If the given option 294 * is a boolean option and is currently unset, the returned value is 295 * {@link Option#UNSET}. If the given option is a <i>size</i> 296 * option, the returned value is in bytes. If the given option is a 297 * <i>time</i> option, the returned value is in nanoseconds. If the 298 * given option is {@link Option#bufpolicy bufpolicy}, the returned 299 * value is one of {@link Option#BUFPOLICY_RING BUFPOLICY_RING}, 300 * {@link Option#BUFPOLICY_FILL BUFPOLICY_FILL}, or {@link 301 * Option#BUFPOLICY_SWITCH BUFPOLICY_SWITCH}. If the given option 302 * is {@link Option#bufresize bufresize}, the returned value is one 303 * of {@link Option#BUFRESIZE_AUTO BUFRESIZE_AUTO} or {@link 304 * Option#BUFRESIZE_MANUAL BUFRESIZE_MANUAL}. 305 * 306 * @see #setOption(String option) 307 * @see #unsetOption(String option) 308 * @see #setOption(String option, String value) 309 * @see Option 310 */ getOption(String option)311 public long getOption(String option) throws DTraceException; 312 313 /** 314 * Reports whether or not this consumer is open. 315 * 316 * @return {@code true} if and only if {@link #open(OpenFlag[] 317 * flags) open()} has been called on this consumer and {@link 318 * #close()} has not 319 */ isOpen()320 public boolean isOpen(); 321 322 /** 323 * Reports whether or not it is valid to call {@link #go()}. 324 * 325 * @return {@code true} if and only if at least one program has been 326 * compiled, all compiled programs have been enabled, {@code go()} 327 * has not already been called, and {@link #close()} has not been 328 * called 329 */ isEnabled()330 public boolean isEnabled(); 331 332 /** 333 * Reports whether or not this consumer is running. There may be a 334 * delay after calling {@link #go()} before this consumer actually 335 * starts running (listeners are notified by the {@link 336 * ConsumerListener#consumerStarted(ConsumerEvent e) 337 * consumerStarted()} method). 338 * 339 * @return {@code true} if this consumer is running, {@code false} 340 * otherwise 341 */ isRunning()342 public boolean isRunning(); 343 344 /** 345 * Reports whether or not this consumer is closed. A closed 346 * consumer cannot be reopened. 347 * <p> 348 * Note that a closed consumer is different from a consumer that has 349 * not yet been opened. 350 * 351 * @return {@code true} if {@link #close()} has been called on this 352 * consumer, {@code false} otherwise 353 */ isClosed()354 public boolean isClosed(); 355 356 /** 357 * Begin tracing and start a background thread to consume generated 358 * probe data. 359 * 360 * @throws IllegalStateException if not {@link #isEnabled()} 361 * @throws DTraceException if an exception occurs in the native 362 * DTrace library 363 * @see #go(ExceptionHandler h) 364 * @see #open(OpenFlag[] flags) 365 * @see #compile(String program, String[] macroArgs) 366 * @see #compile(File program, String[] macroArgs) 367 * @see #enable() 368 * @see #stop() 369 * @see #close() 370 */ go()371 public void go() throws DTraceException; 372 373 /** 374 * Begin tracing and start a background thread to consume generated 375 * probe data. Handle any exception thrown in the consumer thread 376 * with the given handler. 377 * 378 * @throws IllegalStateException if not {@link #isEnabled()} 379 * @throws DTraceException if an exception occurs in the native 380 * DTrace library 381 * @see #go() 382 */ go(ExceptionHandler h)383 public void go(ExceptionHandler h) throws DTraceException; 384 385 /** 386 * Stops all tracing, as well as the background thread started by 387 * {@link #go()} to consume generated probe data. A stopped 388 * consumer cannot be restarted. It is necessary to {@code close()} 389 * a stopped consumer to release the system resources it holds. 390 * <p> 391 * A consumer may stop on its own in response to the {@code exit()} 392 * action (see <b>{@code exit()}</b> in the <a 393 * href=http://dtrace.org/guide/chp-actsub.html#chp-actsub-5> 394 * <b>Special Actions</b></a> section of the <b>Actions and 395 * Subroutines</b> chapter of the <i>Dynamic Tracing 396 * Guide</i>). Similarly, a consumer stops automatically if it has 397 * at least one target process and all its target processes have 398 * completed (see {@link #createProcess(String command) 399 * createProcess()} and {@link #grabProcess(int pid) 400 * grabProcess()}). A consumer also stops automatically if it 401 * encounters an exception while consuming probe data. In these 402 * cases it is not necessary to call {@code stop()}. If a consumer 403 * stops for any reason (an explicit call to {@code stop()} or any 404 * of the reasons just given), listeners are notified through the 405 * {@link ConsumerListener#consumerStopped(ConsumerEvent e) 406 * consumerStopped()} method. 407 * <p> 408 * Note that a call to {@code stop()} blocks until the background 409 * thread started by {@code go()} actually stops. After {@code 410 * stop()} returns, a call to {@link #isRunning()} returns {@code 411 * false}. If a {@code DTraceException} is thrown while stopping 412 * this consumer, it is handled by the handler passed to {@link 413 * #go(ExceptionHandler h)} (or a default handler if none is 414 * specified). 415 * 416 * @throws IllegalStateException if called before {@link #go()} or 417 * if {@code stop()} was already called 418 * @see #go() 419 * @see #abort() 420 * @see #close() 421 */ stop()422 public void stop(); 423 424 /** 425 * Aborts the background thread started by {@link #go()}. {@code 426 * abort()} is effectively the same as {@link #stop()} except that 427 * it does not block (i.e. it does not wait until the background 428 * thread actually stops). {@link #isRunning()} is likely {@code 429 * true} immediately after a call to {@code abort()}, since an 430 * aborted consumer stops at a time specified as later. 431 * Specifically, a call to {@code abort()} stops tracing just before 432 * the next {@link ConsumerListener#intervalBegan(ConsumerEvent e) 433 * intervalBegan()} event and stops consuming probe data by the 434 * subsequent {@link ConsumerListener#intervalEnded(ConsumerEvent e) 435 * intervalEnded()} event. When the aborted consumer actually 436 * stops, listeners are notified in the {@link 437 * ConsumerListener#consumerStopped(ConsumerEvent e) 438 * consumerStopped()} method, where it is convenient to {@link 439 * #close()} the stopped consumer after requesting the final 440 * aggregate. 441 * <p> 442 * The {@code abort()} and {@code stop()} methods have slightly 443 * different behavior when called <i>just after</i> {@code go()} but 444 * <i>before</i> the consumer actually starts running: It is 445 * possible to {@code stop()} a consumer before it starts running 446 * (resulting in a {@code consumerStopped()} event without a 447 * matching {@code consumerStarted()} event), whereas an aborted 448 * consumer will not stop until after it starts running, when it 449 * completes a single interval (that interval does not include 450 * sleeping to wait for traced probe data). Calling {@code abort()} 451 * before {@code go()} is legal and has the same effect as calling 452 * it after {@code go()} and before the consumer starts running. 453 * The last behavior follows from the design: You do not know the 454 * state of a consumer after calling {@code abort()}, nor is it 455 * necessary to know the state of a consumer before calling {@code 456 * abort()}. That may be preferable, for example, when you want to 457 * abort a consumer opened and started in another thread. 458 * 459 * @see #stop() 460 */ abort()461 public void abort(); 462 463 /** 464 * Closes an open consumer and releases the system resources it was 465 * holding. If the consumer is running, {@code close()} will {@link 466 * #stop()} it automatically. A closed consumer cannot be 467 * reopened. Closing a consumer that has not yet been opened makes 468 * it illegal to open that consumer afterwards. It is a no-op to 469 * call {@code close()} on a consumer that is already closed. 470 * 471 * @see #open(OpenFlag[] flags) 472 */ close()473 public void close(); 474 475 /** 476 * Adds a listener for probe data generated by this consumer. 477 */ addConsumerListener(ConsumerListener l)478 public void addConsumerListener(ConsumerListener l); 479 480 /** 481 * Removes a listener for probe data generated by this consumer. 482 */ removeConsumerListener(ConsumerListener l)483 public void removeConsumerListener(ConsumerListener l); 484 485 /** 486 * Gets a snapshot of all aggregations except those that have 487 * already been captured in a {@link PrintaRecord}. Does not clear 488 * any aggregation. 489 * <p> 490 * Provides a programmatic alternative to the {@code printa(}) 491 * action (see <a 492 * href=http://dtrace.org/guide/chp-fmt.html#chp-fmt-printa> 493 * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 494 * chapter of the <i>Dynamic Tracing Guide</i>). 495 * 496 * @throws IllegalStateException if called before {@link #go()} or 497 * after {@link #close()} 498 * @throws DTraceException if an exception occurs in the native 499 * DTrace library 500 * @see #getAggregate(Set includedAggregationNames, Set 501 * clearedAggregationNames) 502 */ getAggregate()503 public Aggregate getAggregate() throws DTraceException; 504 505 /** 506 * Gets a snapshot of all the specified aggregations except those 507 * that have already been captured in a {@link PrintaRecord}. Does 508 * not clear any aggregation. 509 * <p> 510 * Provides a programmatic alternative to the {@code printa(}) 511 * action (see <a 512 * href=http://dtrace.org/guide/chp-fmt.html#chp-fmt-printa> 513 * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 514 * chapter of the <i>Dynamic Tracing Guide</i>). 515 * 516 * @param includedAggregationNames if {@code null}, all available 517 * aggregations are included; if non-null, only those aggregations 518 * specifically named by the given set are included 519 * @throws IllegalStateException if called before {@link #go()} or 520 * after {@link #close()} 521 * @throws DTraceException if an exception occurs in the native 522 * DTrace library 523 * @see #getAggregate(Set includedAggregationNames, Set 524 * clearedAggregationNames) 525 */ getAggregate(Set <String> includedAggregationNames)526 public Aggregate getAggregate(Set <String> includedAggregationNames) 527 throws DTraceException; 528 529 /** 530 * Gets a snapshot of all the specified aggregations except those 531 * that have already been captured in a {@link PrintaRecord}, with 532 * the side effect of atomically clearing any subset of those 533 * aggregations. Clearing an aggregation resets all of its values 534 * to zero without removing any of its keys. Leave aggregations 535 * uncleared to get running totals, otherwise specify that an 536 * aggregation be cleared to get values per time interval. Note 537 * that once an aggregation is captured in a {@code PrintaRecord} 538 * (as a result of the {@code printa()} action), it is no longer 539 * available to the {@code getAggregate()} method. 540 * <p> 541 * Provides a programmatic alternative to the {@code printa(}) (see 542 * <a 543 * href=http://dtrace.org/guide/chp-fmt.html#chp-fmt-printa> 544 * <b>{@code printa()}</b></a> in the <b>Output Formatting</b> 545 * chapter of the <i>Dynamic Tracing Guide</i>) and {@code 546 * clear()} actions. 547 * 548 * @param includedAggregationNames if {@code null}, all available 549 * aggregations are included; if non-null, only those aggregations 550 * specifically named by the given set are included 551 * @param clearedAggregationNames if {@code null}, all available 552 * aggregations are cleared; if non-null, only those aggregations 553 * specifically named by the given set are cleared 554 * @throws IllegalStateException if called before {@link #go()} or 555 * after {@link #close()} 556 * @throws DTraceException if an exception occurs in the native 557 * DTrace library 558 */ getAggregate(Set <String> includedAggregationNames, Set <String> clearedAggregationNames)559 public Aggregate getAggregate(Set <String> includedAggregationNames, 560 Set <String> clearedAggregationNames) throws DTraceException; 561 562 /** 563 * Creates a process by executing the given command on the system 564 * and returns the created process ID. The created process is 565 * suspended until calling {@link #go()} so that the process waits 566 * to do anything until this consumer has started tracing (allowing 567 * a process to be traced from the very beginning of its execution). 568 * The macro variable {@code $target} in a D program will be 569 * replaced by the process ID of the created process. When the 570 * created process exits, this consumer notifies listeners through 571 * the {@link ConsumerListener#processStateChanged(ProcessEvent e) 572 * processStateChanged()} method. 573 * <p> 574 * See the <a 575 * href=http://dtrace.org/guide/chp-script.html#chp-script-4> 576 * <b>Target Process ID</b></a> section of the <b>Scripting</b> 577 * chapter of the <i>Dynamic Tracing Guide</i>. 578 * 579 * @param command a string whose first token is assumed to be the 580 * name of the command and whose subsequent tokens are the arguments 581 * to that command. 582 * @return ID of the created process (pid) 583 * @throws NullPointerException if the given command is {@code null} 584 * @throws IllegalArgumentException if the given command is empty or 585 * contains only whitespace 586 * @throws IllegalStateException if called before {@link 587 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 588 * or if the consumer is closed 589 * @throws DTraceException if the process cannot be created 590 * @see #grabProcess(int pid) 591 */ createProcess(String command)592 public int createProcess(String command) throws DTraceException; 593 594 /** 595 * Grabs the specified process and caches its symbol tables. The 596 * macro variable {@code $target} in a D program will be replaced by 597 * the process ID of the grabbed process. When the specified 598 * process exits, this consumer notifies listeners through the 599 * {@link ConsumerListener#processStateChanged(ProcessEvent e) 600 * processStateChanged()} method. 601 * <p> 602 * See the <a 603 * href=http://dtrace.org/guide/chp-script.html#chp-script-4> 604 * <b>Target Process ID</b></a> section of the <b>Scripting</b> 605 * chapter of the <i>Dynamic Tracing Guide</i>. 606 * 607 * @param pid process ID of the process to be grabbed 608 * @throws IllegalStateException if called before {@link 609 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 610 * or if the consumer is closed 611 * @throws DTraceException if the process cannot be grabbed 612 * @see #createProcess(String command) 613 */ grabProcess(int pid)614 public void grabProcess(int pid) throws DTraceException; 615 616 /** 617 * Lists probes that match the given probe description. See {@link 618 * ProbeDescription} for information about pattern syntax and 619 * wildcarding. 620 * 621 * @param filter use {@link ProbeDescription#EMPTY} to get all 622 * probes, otherwise get only those probes that match the given 623 * filter 624 * @return a non-null list of probe descriptions 625 * @throws IllegalStateException if called before {@link 626 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 627 * or if the consumer is closed 628 * @throws DTraceException if an exception occurs in the native 629 * DTrace library 630 * @see #open(OpenFlag[] flags) 631 * @see #close() 632 * @see #listProbeDetail(ProbeDescription filter) 633 * @see #listProgramProbes(Program program) 634 */ listProbes(ProbeDescription filter)635 public List <ProbeDescription> listProbes(ProbeDescription filter) 636 throws DTraceException; 637 638 /** 639 * Lists probes that match the given probe description and includes 640 * detail such as stability information about each listed probe. 641 * 642 * @param filter use {@link ProbeDescription#EMPTY} to get all 643 * probes, otherwise get only those probes that match the given 644 * filter 645 * @return a non-null list of probe detail 646 * @throws IllegalStateException if called before {@link 647 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 648 * or if the consumer is closed 649 * @throws DTraceException if an exception occurs in the native 650 * DTrace library 651 * @see #listProbes(ProbeDescription filter) 652 * @see #listProgramProbeDetail(Program program) 653 */ listProbeDetail(ProbeDescription filter)654 public List <Probe> listProbeDetail(ProbeDescription filter) 655 throws DTraceException; 656 657 /** 658 * Lists probes that match the given compiled program. A probe 659 * matches a D program if that program contains any matching probe 660 * description. 661 * 662 * @param program a {@code Program} identifier returned by {@link 663 * #compile(String program, String[] macroArgs) compile(String 664 * program, ...)} or {@link #compile(File program, String[] 665 * macroArgs) compile(File program, ...)} 666 * @return a non-null list of probe descriptions 667 * @throws NullPointerException if the given program identifier is 668 * {@code null} 669 * @throws IllegalArgumentException if the specified program was not 670 * compiled by this consumer 671 * @throws IllegalStateException if called before {@link 672 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 673 * or if the consumer is closed 674 * @throws DTraceException if an exception occurs in the native 675 * DTrace library 676 * @see #listProbes(ProbeDescription filter) 677 */ listProgramProbes(Program program)678 public List <ProbeDescription> listProgramProbes(Program program) 679 throws DTraceException; 680 681 /** 682 * Lists probes that match the given compiled program and includes 683 * detail such as stability information about each listed probe. 684 * 685 * @param program a {@code Program} identifier returned by {@link 686 * #compile(String program, String[] macroArgs) compile(String 687 * program, ...)} or {@link #compile(File program, String[] 688 * macroArgs) compile(File program, ...)} 689 * @return a non-null list of probe detail 690 * @throws NullPointerException if the given program identifier is 691 * {@code null} 692 * @throws IllegalArgumentException if the specified program was not 693 * compiled by this consumer 694 * @throws IllegalStateException if called before {@link 695 * #open(Consumer.OpenFlag[] flags) open()} or after {@link #go()}, 696 * or if the consumer is closed 697 * @throws DTraceException if an exception occurs in the native 698 * DTrace library 699 * @see #listProgramProbes(Program program) 700 * @see #listProbeDetail(ProbeDescription filter) 701 */ listProgramProbeDetail(Program program)702 public List <Probe> listProgramProbeDetail(Program program) 703 throws DTraceException; 704 705 /** 706 * Gets the kernel function name for the given 32-bit kernel 707 * address. 708 * 709 * @param address 32-bit kernel function address, such as the value 710 * of a {@link Tuple} member in an {@link AggregationRecord} to be 711 * converted for display 712 * @return the result of kernel function lookup as one of the 713 * following:<ul><li>{@code module`function}</li> 714 * <li>{@code module`function+offset}</li> 715 * <li>{@code module`address}</li> 716 * <li>{@code address}</li></ul> where {@code module} and {@code 717 * function} are names, and {@code offset} and {@code address} are 718 * integers in hexadecimal format preceded by "{@code 0x}". {@code 719 * offset} is the number of bytes from the beginning of the 720 * function, included when non-zero. {@code address} is simply the 721 * hex form of the input paramater, returned when function lookup 722 * fails. The exact details of this format are subject to change. 723 * @throws IllegalStateException if called before {@link #go()} or 724 * after {@link #close()} 725 * @see #lookupKernelFunction(long address) 726 */ lookupKernelFunction(int address)727 public String lookupKernelFunction(int address); 728 729 /** 730 * Gets the kernel function name for the given 64-bit kernel 731 * address. 732 * 733 * @param address 64-bit kernel function address 734 * @return kernel function name 735 * @throws IllegalStateException if called before {@link #go()} or 736 * after {@link #close()} 737 * @see #lookupKernelFunction(int address) 738 */ lookupKernelFunction(long address)739 public String lookupKernelFunction(long address); 740 741 /** 742 * Gets the user function name for the given 32-bit user address and 743 * process ID. 744 * 745 * @param pid ID of the user process containing the addressed 746 * function 747 * @param address 32-bit user function address, such as the value 748 * of a {@link Tuple} member in an {@link AggregationRecord} to be 749 * converted for display. 750 * @return result of user function lookup as one of the 751 * following:<ul> <li>{@code module`function}</li> 752 * <li>{@code module`function+offset}</li> 753 * <li>{@code module`address}</li> 754 * <li>{@code address}</li></ul> where {@code module} and {@code 755 * function} are names, and {@code offset} and {@code address} are 756 * integers in hexadecimal format preceded by "{@code 0x}". {@code 757 * offset} is the number of bytes from the beginning of the 758 * function, included when non-zero. {@code address} is simply the 759 * hex form of the input paramater, returned when function lookup 760 * fails. The exact details of this format are subject to change. 761 * @throws IllegalStateException if called before {@link #go()} or 762 * after {@link #close()} 763 * @see #lookupUserFunction(int pid, long address) 764 */ lookupUserFunction(int pid, int address)765 public String lookupUserFunction(int pid, int address); 766 767 /** 768 * Gets the user function name for the given 64-bit user address and 769 * process ID. 770 * 771 * @param pid ID of the user process containing the addressed 772 * function 773 * @param address 64-bit user function address 774 * @return user function name 775 * @throws IllegalStateException if called before {@link #go()} or 776 * after {@link #close()} 777 * @see #lookupUserFunction(int pid, int address) 778 */ lookupUserFunction(int pid, long address)779 public String lookupUserFunction(int pid, long address); 780 781 /** 782 * Gets the version of the native DTrace library. 783 * 784 * @return version string generated by the native DTrace library 785 * (same as the output of {@code dtrace(8)} with the {@code -V} 786 * option) 787 */ getVersion()788 public String getVersion(); 789 } 790