Chapter 1 Introduction

DTrace is a comprehensive dynamic tracing facility that is built into Solaris. DTrace can be used by administrators and developers, and can safely be used on live production systems. DTrace enables you to examine the behavior of user programs as well as the behavior of the operating system. Users of DTrace can create custom programs with the D scripting language. Custom programs provide the ability to dynamically instrument the system. Custom programs provide immediate, concise answers to specific questions about the behavior of particular applications.

DTrace Capabilities

The DTrace framework provides instrumentation points that are called probes. A DTrace user can use a probe to record and display relevant information about a kernel or user process. Each DTrace probe is activated by a specific behavior. This probe activation is referred to as firing. As an example, consider a probe that fires on entry into an arbitrary kernel function. This example probe can display the following information:

• Any argument that is passed to the function

• Any global variable in the kernel

• A timestamp that indicates when the function was called

• A stack trace that indicates the section of code that called the function

• The process that was running at the time the function was called

• The thread that made the function call

When a probe fires, you can specify a particular action for DTrace to take. A DTrace action usually records an interesting aspect of system behavior, such as a timestamp or a function argument.

Probes are implemented by providers. A probe provider is a kernel module that enables a given probe to fire. For example, the function boundary tracing provider fbt provides entry and return probes for almost every function in every kernel module.

DTrace has significant data management capabilities. These capabilities enable DTrace users to prune the data reported by probes, avoiding the overhead involved in generating and then filtering unwanted data. DTrace also provides mechanisms for tracing during the boot process and for retrieving data from a kernel crash dump. All of the instrumentation in DTrace is dynamic. Probes are enabled discretely at the time that the probes are used, and inactive probes present no instrumented code.

A DTrace consumer is any process that interacts with the DTrace framework. While dtrace(1M) is the primary DTrace consumer, other consumers exist. These additional consumers mostly consist of new versions of existing utilities such as lockstat(1M). The DTrace framework has no limit on the number of concurrent consumers.

The behavior of DTrace can be modified with the use of scripts that are written in the D language, which is structured similarly to C. The D language provides access to kernel C types and kernel static and kernel global variables. The D language supports ANSI C operators.

Architecture overview

The DTrace facility consists of the following components:

• User level consumer programs such as dtrace

• Providers, packaged as kernel modules, that provide probes to gather tracing data

• A library interface that consumer programs use to access the DTrace facility through the dtrace(7D) kernel driver

DTrace Providers

A provider represents a methodology for instrumenting the system. Providers make probes available to the DTrace framework. DTrace sends information to a provider regarding when to enable a probe. When an enabled probe fires, the provider transfers control to DTrace.

Providers are packaged as a set of kernel modules. Each module performs a particular kind of instrumentation to create probes. When you use DTrace, each provider has the ability to publish the probes it can provide to the DTrace framework. You can enable and bind tracing actions to any of the published probes.

Some providers have the capability to create new probes based on the user's tracing requests.

DTrace Probes

A probe has the following attributes:

• It is made available by a provider

• It identifies the module and the function that it instruments

• It has a name

These four attributes define a 4–tuple that serves as a unique identifier for each probe, in the format provider:module:function:name. Each probe also has a unique integer identifier.

DTrace Predicates

Predicates are expressions that are enclosed in slashes / /. Predicates are evaluated at probe firing time to determine whether the associated actions should be executed. Predicates are the primary conditional construct used for building more complex control flow in a D program. You can omit the predicate section of the probe clause entirely for any probe. If the predicate section is omitted, the actions are always executed when the probe fires.

Predicate expressions can use any of the previously described D operators. Predicate expressions refer to D data objects such as variables and constants. The predicate expression must evaluate to a value of integer or pointer type. As with all D expressions, a zero value is interpreted as false and any non-zero value is interpreted as true.

DTrace Actions

Actions are user-programmable statements that the DTrace virtual machine executes within the kernel. Actions have the following properties:

• Actions are taken when a probe fires

• Actions are completely programmable in the D scripting language

• Most actions record a specified system state

• An action can change the state of the system in a precisely described way. Such actions are called destructive actions. Destructive actions are not allowed by default.

• Many actions use expressions in the D scripting language

D Scripting Language

You can invoke the DTrace framework directly from the command line with the dtrace command for simple functions. To use DTrace to perform more complex functions, write a script in the D scripting language. Use the -s option to load a specified script for DTrace to use. See Chapter 3, Scripting With the D Language for information about using the D scripting language.