16 DTrace Stability Features

Developers are provided with early access to new technologies, as well as observability tools that enable them peer into the internal implementation details of user and kernel software. Unfortunately, new technologies and internal implementation details are prone to changes because interfaces and implementations evolve and mature when software is upgraded or patched.

Application and interface stability levels are documented using a set of labels to help set user expectations for the kinds of changes that might occur in different types of future releases. No individual stability attribute appropriately describes the arbitrary set of entities and services that can be accessed from a D program. Therefore, DTrace and the D compiler include features to dynamically compute and describe the stability levels of the D programs that you create.

This chapter discusses the DTrace features for determining program stability to help you design stable D programs. You can use these DTrace stability features to inform you of the stability attributes of your D programs or to produce compile-time errors when your program has undesirable interface dependencies.

Stability Levels

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.

Stability Value	Description
Internal	The interface is private to DTrace and represents an implementation detail of DTrace. Internal interfaces might change in minor or micro releases.
Private	The interface is private to Oracle and represents an interface developed for use by other Oracle products that are not yet publicly documented for use by customers and ISVs (independent software vendors). Private interfaces might change in minor or micro releases.
Obsolete	The interface is supported in the current release but is scheduled to be removed, most likely in a future minor release. The D compiler might produce warning messages if you attempt to use an Obsolete interface.
External	The interface is controlled by an entity other than Oracle. Oracle makes no claims regarding either source or binary compatibility for External interfaces between any two releases. Applications based on these interfaces might not work in future releases, including patches that contain External interfaces.
Unstable	The interface provides developers early access to new or rapidly changing technology or to an implementation artifact that is essential for observing or debugging system behavior for which a more stable solution is anticipated in the future. Oracle makes no claims about either source or binary compatibility for Unstable interfaces from one minor release to another.
Evolving	The interface might eventually become Standard or Stable but is still in transition. When non-upward, compatible changes become necessary, they occur in minor and major releases. These changes will be avoided in micro releases whenever possible. If such a change is necessary, it will be documented in the release notes for the affected release. Also, when feasible, migration aids are provided for binary compatibility and continued D program development.
Stable	The interface is a mature interface.
Standard	The interface complies with an industry standard. The corresponding documentation for the interface describes the standard to which the interface conforms. Standards are typically controlled by a standards development organization. Changes can be made to the interface in accordance with approved changes to the standard. This stability level can also apply to interfaces that have been adopted (without a formal standard) by an industry convention. Support is provided for only the specified versions of a standard; support for later versions is not guaranteed.

Dependency Classes

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).

Dependency Class	Description
Unknown	The interface has an unknown set of architectural dependencies. DTrace does not necessarily know the architectural dependencies of all entities, such as the data types defined in the operating system implementation. The Unknown label is typically applied to interfaces of very low stability for which dependencies cannot be computed. The interface might not be available when using DTrace on any architecture other than what you are currently using.
CPU	The interface is specific to the CPU model of the current system. Interfaces with CPU model dependencies might not be available on other CPU implementations, even if those CPUs export the same instruction set architecture (ISA).
Platform	The interface is specific to the hardware platform for the current system. A platform typically associates a set of system components and architectural characteristics. To display the current platform name, use the uname -i command. The interface might not be available on other hardware platforms.
Group	The interface is specific to the hardware platform group for the current system. A platform group typically associates a set of platforms with related characteristics together under a single name. To display the current platform group name, use the uname -m command. The interface is available on other platforms in the platform group, but it might not be available on hardware platforms that are not members of the group.
ISA	The interface is specific to the ISA that is supported by the microprocessors on the current system. The ISA describes a specification for software that can be executed on the microprocessor, including details such as assembly language instructions and registers. To display the native instruction sets that are supported by the system, use the isainfo command. The interface might not be supported on systems that do not export any of the same instruction sets.
Common	The interface is common to all Oracle Linux platforms, regardless of the underlying hardware. DTrace programs and layered applications that depend only on Common interfaces can be executed and deployed on other Oracle Linux platforms with the same Oracle Linux and DTrace revisions. The majority of DTrace interfaces are Common, so you can use them wherever you use Oracle Linux.

Interface Attributes

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.

Stability Computations and Reports

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.

Entity	Attributes
D built-in variable curthread	Stable/Private/Common
D user-defined variable x	Stable/Stable/Common

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.

Stability Enforcement

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