1 /*

     2  * Copyright (c) 2008, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 /**

    27  * This package provides a mechanism for defining and

    28  * inserting tracepoints into Java-technology based applications, which

    29  * can then be monitored by the tracing tools available on the system.

    30  * <p>

    31  * To add tracepoints to a program, you must first decide where to place the

    32  * tracepoints, what the logical names are for these points, what information

    33  * will be available to the tracing mechanisms at each point, and decide upon

    34  * any logical grouping.

    35  * <p>

    36  * You add instrumentation to a program in three steps:

    37  * <ul>

    38  * <li>First, declare tracepoints by creating interfaces to define

    39  * them, and include these interfaces in the program definition.

    40  * The declared interfaces are standard Java technology-based

    41  * interfaces and are compiled with the program.</li>

    42  * <li>Second, add code in the application to create an instance of the

    43  * interface at some point during the initialization of the application,

    44  * using a factory class provided by the system. The reference to the

    45  * instance can be stored as a global static, or passed as context to all

    46  * the places where it is needed.</li>

    47  * <li>Finally, add the actual tracepoints to the desired locations in the

    48  * application by inserting a call to one of the methods defined in the

    49  * interface, via the factory-created reference.</li>

    50  * </ul>

    51  * <p>

    52  * The method calls representing the tracepoints have no logical

    53  * impact on the program.  The side effect of the call is that any

    54  * activated tracing mechanisms will be notified that the tracepoint has

    55  * been hit, and will take whatever actions are appropriate (for example,

    56  * logging  the tracepoint, or triggering a DTrace probe, etc.).  In most

    57  * cases, the impact on performance of adding tracepoints to the application

    58  * will be minimal.

    59  * <p>

    60  * Each logical grouping of tracepoints should be defined in a common

    61  * interface, called a <i>provider</i>.  An application can have one or many

    62  * providers.  Each provider is independent and can be created whenever

    63  * it is appropriate for that provider, for example, when a subsytem is

    64  * initialized.  Providers should be disposed of when they are no longer

    65  * needed, to free up any associated system resources.  Each tracepoint

    66  * in a provider is represented by a method in that interface.  These methods

    67  * are referred to as <i>probes</i>.  The method signature determines the probe

    68  * parameters.  A call to the method with the specified parameters triggers

    69  * the probe and makes its parameter values visible to any associated tracing

    70  * mechanism.

    71  * <p>

    72  * User-defined interfaces which represent providers must extend the

    73  * {@code Provider} interface.  To activate the system-defined

    74  * tracing mechanisms, you must obtain an instance of the

    75  * {@code ProviderFactory} class, and pass the class of the provider to

    76  * the {@code createProvider()} method.  The returned instance is then used to

    77  * trigger the probes later in the application.

    78  * <p>

    79  * In addition to triggering the probes, the provider instance can be used

    80  * to obtain direct references to the {@code Probe} objects, which can be used

    81  * directly for triggering, or can be queried to determine whether the probe is

    82  * currently being traced.  The {@code Provider} interface also defines a

    83  * {@code Provider.dispose()} method which is used to free up any resources

    84  * that might be associated with that provider.

    85  * <p>

    86  * When a probe is triggered, any activated tracing system will be given

    87  * the provider name, the probe name, and the values of the probe arguments.

    88  * The tracing system is free to consume this data is whatever way is

    89  * appropriate.

    90  * By default, the provider name is the same as the class name of the interface

    91  * that defines the provider. Similarly, the probe name is

    92  * the name of the method that defines the probe. These default values

    93  * can be over-ridden by annotations.  The provider definition can be

    94  * annotated with the {@code @ProviderName} annotation, whose value will

    95  * indicate the provider name that the tracing system will use.  Similarly,

    96  * the {@code @ProbeName} annotation annotates a declared method and

    97  * indicates the probe name that should be used in the place of the

    98  * method name.  These annotations can be used to define providers and

    99  * probes with the same name, in cases where the semantics of the Java language

   100  * may prevent this.

   101  * <p>

   102  * Here is a very small and simple usage example:

   103  * <p>

   104  *

   105 <PRE>

   106    import com.sun.tracing.Provider;

   107    import com.sun.tracing.ProviderFactory;

   108 

   109    interface MyProvider extends Provider {

   110        void startProbe();

   111        void finishProbe(int value);

   112    }

   113 

   114    public class MyApplication {

   115        public static void main(String argv[]) {

   116            ProviderFactory factory = ProviderFactory.getDefaultFactory();

   117            MyProvider trace = factory.createProvider(MyProvider.class);

   118 

   119            trace.startProbe();

   120            int result = foo();

   121            trace.finishProbe(result);

   122 

   123            trace.dispose();

   124        }

   125    }

   126 </PRE>

   127  * <p>

   128  * The Java Development Kit (JDK) currently only includes one system-defined

   129  * tracing framework: DTrace. DTrace is enabled automatically whenever an

   130  * application is run on a system and a JDK release that supports it. When

   131  * DTrace is enabled, probes are made available for listing and matching by

   132  * DTrace scripts as soon as the provider is created. At the tracepoint, an

   133  * associated DTrace script is informed of the creation of the provider, and

   134  * it takes whatever action it is designed to take. Tracepoints in the

   135  * program have the following DTrace probe names:<br>

   136  *   {@code <provider><pid>:<module>:<function>:<probe>}

   137  * Where:

   138  * <ul>

   139  * <li>{@code <provider>} the provider name as specified by the application</li>

   140  * <li>{@code <pid>} the operating system process ID</li>

   141  * <li>{@code <module>} undefined, unless specified by the application</li>

   142  * <li>{@code <function>} undefined, unless specified by the application</li>

   143  * <li>{@code <probe>} the probe name as specified by the application</li>

   144  * </ul>

   145  * <p>

   146  * The {@code com.sun.tracing.dtrace} package contains additional

   147  * annotations that can be used to control the names used for the

   148  * <code>module</code> and <code>function</code> fields, as well as annotations

   149  * that can be added to the provider to control probe stability and dependency

   150  * attributes.

   151  * <p>

   152  * Integer, float and string probe parameters are made available to DTrace

   153  * using

   154  * the built-in argument variables, {@code arg0 ... arg_n}.  Integer-types

   155  * are passed by value (boxed values are unboxed), floating-point types are

   156  * passed as encoded integer

   157  * arguments, and {@code java.lang.String} objects are converted

   158  * to UTF8 strings, so they can be read into the DTrace script using the

   159  * {@code copyinstr()} intrinsic.  Non-string and non-boxed primitive

   160  * reference arguments are only

   161  * placeholders and have no value.

   162  * <p>

   163  * Using the example above, with a theoretical process ID of 123, these are

   164  * the probes that can be traced from DTrace:

   165 <PRE>

   166     MyProvider123:::startProbe

   167     MyProvider123:::finishProbe

   168 </PRE>

   169  * When {@code finishProbe} executes, {@code arg0} will contain the

   170  * value of {@code result}.

   171  * <p>

   172  * The DTrace tracing mechanism is enabled for all providers, apart from in the

   173  * following circumstances:

   174  * <ul>

   175  * <li>DTrace is not supported on the underlying system.</li>

   176  * <li>The property {@code com.sun.tracing.dtrace} is set to "disable".</li>

   177  * <li>The RuntimePermission {@code com.sun.tracing.dtrace.createProvider}

   178  * is denied to the process.</li>

   179  * </ul>

   180  * <p>

   181  */

   182 

   183 package com.sun.tracing;