SDT Provider

The Statically Defined Tracing (SDT) provider (sdt) creates probes at sites that a software programmer has formally designated. Thus, the SDT provider is chiefly of interest only to developers of new providers. Most users access SDT only indirectly by using other providers.

The SDT mechanism enables programmers to consciously choose locations of interest to users of DTrace and to convey some semantic knowledge about each location through the probe name.

Importantly, SDT can act as a metaprovider by registering probes so that they appear to come from other providers, such as io, proc, and sched.

Both the name stability and the data stability of the probes are Private, which reflects the kernel's implementation and should not be interpreted as a commitment to preserve these interfaces.

Creating sdt Probes

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

DTrace also provides a mechanism for application developers to define user-space static probes.

Declaring Probes

The sdt probes are declared by using the DTRACE_PROBE macro from <linux/sdt.h>.

The module name and function name of an SDT-based probe correspond to the kernel module name and function name where the probe is declared. DTrace includes the kernel module name and function name as part of the tuple used to identify the probe in the probe description, so you don't need to explicitly include this information when devising the probe name. You can still specify the module and function name when referring to the probe in a DTrace program to prevent namespace collisions. Use the dtrace -l -m mymodule command to list the probes that mymodule has installed and the full names that are seen by DTrace users.

The name of the probe depends on the name that's provided in the DTRACE_PROBE macro. If the name doesn't contain two consecutive underscores (__), the name of the probe is as written in the macro. If the name contains two consecutive underscores, the probe name converts the consecutive underscores to a single dash (-). For example, if a DTRACE_PROBE macro specifies transaction__start, the SDT probe is named transaction-start. This substitution enables C code to provide macro names that aren't valid C identifiers without specifying a string.

SDT can also act as a metaprovider by registering probes so that they appear to come from other providers, such as io, proc, and sched, which don't have dedicated modules of their own. For example, kernel/exit.c contains calls to the DTRACE_PROC macro, which are defined as follows in <linux/sdt.h>:

# define DTRACE_PROC(name) \
         DTRACE_PROBE(__proc_##name);

Probes that use such macros appear to come from a provider other than sdt. The leading double underscore, provider name, and trailing underscore in the name argument are used to match the provider and aren't included in the probe name.

sdt Probe Arguments

The arguments for each sdt probe are the arguments that are specified in the kernel source code in the corresponding DTRACE_PROBE macro reference. When declaring sdt probes, you can minimize their disabled probe effect by not dereferencing pointers and by not loading from global variables in the probe arguments. Both pointer dereferencing and global variable loading can be done safely in D functions that enable probes, so DTrace users can request these functions only when they're needed.

sdt Stability

The sdt provider uses DTrace's stability mechanism to describe its stabilities. These values are listed 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