11.4 sdt provider

11.4.1 Creating SDT Probes
11.4.2 Stability

The Statically Defined Tracing (SDT) provider creates probes at sites that a software programmer has formally designated. The SDT mechanism allows programmers to consciously choose locations of interest to users of DTrace and to convey some semantic knowledge about each location through the probe name.

As the sdt probes that are defined for Oracle Linux kernel are likely to change over time, they are not listed here. Both the name stability and data stability of the probes are Private, which reflects the kernel's implementation and should not be interpreted a commitment to preserve these interfaces. For more information about the DTrace stability mechanism, see Chapter 15, Stability.

11.4.1 Creating SDT Probes

If you are a device driver developer, you might be interested in creating your own SDT probes for your Oracle Linux driver. The disabled probe effect of SDT is essentially the cost of several no-operation machine instructions. You are therefore encouraged to add SDT probes to your device drivers as needed. Unless these probes negatively affect performance, you can leave them in your shipping code.

DTrace also provides a mechanism for application developers to define user-space static probes, as described in Chapter 13, Statically Defined Tracing for User Applications.

11.4.1.1 Declaring Probes

SDT probes are declared using the DTRACE_PROBE, DTRACE_PROBE1, DTRACE_PROBE2, DTRACE_PROBE3, and DTRACE_PROBE4 macros from <sys/sdt.h>. The module name and function name of an SDT-based probe corresponds to the kernel module and function of the probe. The name of the probe depends on the name given in the DTRACE_PROBEn macro. If the name does not contains two consecutive underbars (__), the name of the probe is as written in the macro. If the name contains two consecutive underbars, the probe name converts the consecutive underbars to a single dash (-). For example, if a DTRACE_PROBE macro specifies transaction__start, the SDT probe is named transaction-start. This substitution allows C code to provide macro names that are not valid C identifiers without specifying a string.

DTrace includes the kernel module name and function name as part of the tuple identifying a probe, so you do not need to include this information in the probe name to prevent name space collisions. You can use the command dtrace -l -P sdt -m module on your driver module to list the probes you have installed and the full names that are seen by DTrace users.

11.4.1.2 Probe Arguments

The arguments for each SDT probe are the arguments specified in the corresponding DTRACE_PROBEn macro reference. The number of arguments depends on which macro was used to create the probe: DTRACE_PROBE1 specifies one argument, DTRACE_PROBE2 specifies two arguments, and so on. When declaring your SDT probes, you can minimize their disabled probe effect by not dereferencing pointers and not loading from global variables in the probe arguments. Both pointer dereferencing and global variable loading may be done safely in D actions that enable probes, so DTrace users can request these actions only when they are needed.

11.4.2 Stability

The sdt provider uses DTrace's stability mechanism to describe its stabilities, as shown in the following table.

Element

Name Stability

Data Stability

Dependency Class

Provider

Evolving

Evolving

ISA

Module

Private

Private

Unknown

Function

Private

Private

Unknown

Name

Private

Private

ISA

Arguments

Private

Private

ISA

For more information about the stability mechanism, refer to Chapter 15, Stability.