DTrace provides two types of stability attributes for entities like built-in variables, functions and probes: a stability level and an architectural dependency class. The DTrace stability level assists you in making risk assessments when developing scripts and tools that are based on DTrace by indicating how likely it is for an interface or DTrace entity to change in a future release or patch. The DTrace dependency class indicates whether an interface is common to all Oracle Linux platforms and processors or whether it is associated with a particular architecture. The two types of attributes that are used to describe interfaces can vary independently.

The stability values that are used by DTrace are described in the following table and are listed in order, from the lowest stability to the highest stability. Applications that depend only on Stable interfaces should reliably continue to function on future minor releases and will not be broken by interim patches. The less stable interfaces allow for experimentation, prototyping, tuning, and debugging on your current system. These less stable interfaces should be used with the understanding that they might change and become incompatible or even be dropped or replaced with alternatives in future minor releases.

DTrace stability values also help you understand the stability of the software entities that you are observing, in addition to the stability of the DTrace interfaces themselves. Therefore, DTrace stability values also indicate how likely your D programs and layered tools are to require corresponding changes when you upgrade or change the software stack that you are observing.

Because Oracle Linux and DTrace support a variety of operating platforms and processors, DTrace also labels interfaces with a dependency class, which indicates whether an interface is common to all Oracle Linux platforms and processors or whether the interface is associated with a particular system architecture. The dependency class is orthogonal to the stability levels previously described in this document. For example, a DTrace interface can be Stable, but only supported on x86_64 microprocessors. Or, the interface can be Unstable, but common to all Oracle Linux platforms. The DTrace dependency classes are described in the following table and listed in order, from least common (most specific to a particular architecture), to most common (common to all architectures).

DTrace describes interfaces by using a triplet of attributes consisting of two stability levels and one dependency class. By convention, the interface attributes are written in the following order and are separated by slashes:

                  name_stability / data_stability / dependency_class

The name stability of an interface describes the stability level that is associated with its name, as it appears in your D program or on the dtrace command line. For example, the execname D variable is a Stable name.

The data stability of an interface is distinct from the stability that is associated with the interface name. This stability level describes the commitment to maintain the data formats that are used by the interface and any associated data semantics.

The dependency class of an interface is distinct from its name and data stability and describes whether the interface is specific to the current operating platform or microprocessor.

DTrace and the D compiler track the stability attributes for all of the following DTrace interface entities: providers, probe descriptions, D variables, D functions, types, and program statements. These interface entities are described later in this chapter. Note that all three values can vary independently. For example, the curthread D variable has Stable/Private/Common attributes: the variable name is Stable and is Common to all Oracle Linux platforms. Note that this variable provides access to a Private data format that is an artifact of the Oracle Linux kernel implementation. Most D variables are provided with Stable/Stable/Common attributes, as are the variables you define.

The D compiler performs stability computations for each of the probe descriptions and action statements in your D programs. You can use the dtrace command with the -v option to display a report of your program's stability, as shown in the follow example that uses a program written on the command line:

# dtrace -v -n dtrace:::BEGIN'{exit(0);}'
dtrace: description 'dtrace:::BEGIN' matched 1 probe

Stability attributes for description dtrace:::BEGIN:

	Minimum Probe Description Attributes
		Identifier Names: Stable
		Data Semantics:   Stable
		Dependency Class: Common

	Minimum Statement Attributes
		Identifier Names: Stable
		Data Semantics:   Stable
		Dependency Class: Common

CPU     ID                    FUNCTION:NAME
  0      1                           :BEGIN 

You can also choose to combine the -v option with the -e option, which directs the dtrace command to compile, but not execute your D program, so that you can determine program stability without enabling any probes and executing your program, as shown in the following stability report:

# dtrace -ev -n dtrace:::BEGIN'{trace(curthread->parent);}'

Stability data for description dtrace:::BEGIN:

    Minimum probe description attributes
        Identifier Names: Evolving
        Data Semantics: Evolving
        Dependency Class: Common

    Minimum probe statement attributes
        Identifier Names: Stable
        Data Semantics: Private
        Dependency Class: Common

In this example, notice that in the new program, the D curthread variable is referenced. This variable has a Stable name, but Private data semantics: if you look at it, you are accessing Private implementation details of the kernel. This status is now reflected in the program's stability report. Stability attributes in the program report are computed by selecting the minimum stability level and class from the corresponding values for each interface attributes triplet.

Stability attributes are computed for a probe description by taking the minimum stability attributes of all of the specified probe description fields, according to the attributes that are published by the provider. The attributes of the available DTrace providers are shown in the section corresponding to each provider. DTrace providers export a stability attributes triplet for each of the four description fields for all of the probes published by that provider. Therefore, a provider's name can have a greater stability than the individual probes that it exports. For simplicity, most providers use a single set of attributes for all of the individual module function name values they publish. Providers also specify attributes for the args[] array because the stability of any probe arguments varies by provider.

If the provider field is not specified in a probe description, then the description is assigned the Unstable/Unstable/Common stability attributes because the description might end up matching probes of providers that do not yet exist when used on a future Oracle Linux release. As such, Oracle does not provide guarantees about the future stability and behavior of this program. You should always explicitly specify the provider when writing your D program clauses. In addition, any probe description fields that contain pattern matching characters or macro variables, such as $1, are treated as unspecified because these description patterns might expand to match providers or probes to be released in future versions of DTrace and Oracle Linux. For more details on pattern matching characters and macro variables, see D Program Structureand Scripting.

Stability attributes are computed for most D language statements by taking the minimum stability and class of the entities in the statement. The D language entities and their stability attributes are listed in the following table.

For example, if you write the following D program statement, the resulting attributes of the statement are Stable/Private/Common and the minimum attributes are associated with the curthread and x operands:

x += curthread->prio;

The stability of an expression is computed by taking the minimum stability attributes of each of the operands.

Any D variables that you define in your program are automatically assigned the Stable/Stable/Common attributes. In addition, the D language grammar and D operators are implicitly assigned these three attributes. References to kernel symbols by using the back quote (`) operator are always assigned the Private/Private/Unknown attributes because they reflect implementation artifacts. Types that you define in your D program source code, specifically those that are associated with the C and D type namespace, are assigned the Stable/Stable/Common attributes. Types that are defined in the operating system implementation and provided by other type namespaces are assigned the Private/Private/Unknown attributes. The D type cast operator yields an expression with stability attributes that are the minimum of the input expression's attributes and the attributes of the cast output type.

If you use the C preprocessor to include C system header files, these types are associated with the C type namespace and are assigned the Stable/Stable/Common attributes, as the D compiler automatically assumes you are taking responsibility for these declarations. It is therefore possible to be misled about your program's stability if you use the C preprocessor to include a header file containing implementation artifacts. You should always consult the documentation corresponding to the header files that you are including so that you can determine the correct stability levels.

When developing a DTrace script or layered tool, you might want to identify the specific source of stability issues or ensure that your program has a desired set of stability attributes. You can use the -x amin=_attributes_ option with the dtrace command to force the D compiler to produce an error whenever any attributes computation results in a triplet of attributes less than the minimum values that you specify on the command line.

The following example demonstrates the use of the -x amin option using a snippet of D program source. Note that attributes are specified with three labels that are delimited /, in the usual order:

# dtrace -x amin=Evolving/Evolving/Common \
  -ev -n dtrace:::BEGIN’{trace(curthread->parent);}’
dtrace: invalid probe specifier dtrace:::BEGIN{trace(curthread->parent);}: \
    in action list: attributes for scalar curthread (Stable/Private/Common) \
    are less than predefined minimum