... {anchor:top}
h1. {anchor:chp-usdt} Statically Defined Tracing for User Applications
DTrace provides a facility for user application developers to define customized probes in application code to augment the capabilities of the {{pid}} provider. These static probes impose little to no overhead when disabled and are dynamically enabled like all other DTrace probes. You can use static probes to describe application semantics to users of DTrace without exposing or requiring implementation knowledge of your applications. This chapter describes how to define static probes in user applications and how to use DTrace to enable such probes in user processes.
[Top|#top]
h2. {anchor:chp-usdt-1} Choosing the Probe Points
DTrace allows developers to embed static probe points in application code, including both complete applications and shared libraries. These probes can be enabled wherever the application or library is running, either in development or in production. You should define probes that have a semantic meaning that is readily understood by your DTrace user community. For example, you could define {{query-receive}} and {{query-respond}} probes for a web server that correspond to a client submitting a request and the web server responding to that request. These example probes are easily understood by most DTrace users and correspond to the highest level abstractions for the application, rather than lower level implementation details. DTrace users might use these probes to understand the time distribution of requests. If your {{query-receive}} probe presented the URL request strings as an argument, a DTrace user could determine which requests were generating the most disk I/O by combining this probe with the {{io}} provider.\\
\\You should also consider the stability of the abstractions you describe when choosing probe names and locations. Will this probe persist in future releases of the application, even if the implementation changes? Does the probe make sense on all system architectures or is it specific to a particular instruction set? This chapter will discuss the details of how these decisions guide your static tracing definitions.
[Top|#top]
h2. {anchor:chp-usdt-2} Adding Probes to an Application
DTrace probes for libraries and executables are defined in an ELF section in the corresponding application binary. This section describes how to define your probes, add them to your application source code, and augment your application's build process to include the DTrace probe definitions.
[Top|#top]
h3. {anchor:chp-usdt-3} Defining Providers and Probes
You define DTrace probes in a {{.d}} source file which is then used when compiling and linking your application. First, select an appropriate name for your user application provider. The provider name you choose will be appended with the process identifier for each process that is executing your application code. For example, if you chose the provider name {{myserv}} for a web server that was executing as process ID 1203, the DTrace provider name corresponding to this process would be {{myserv1203}}. In your {{.d}} source file, add a provider definition similar to the following example:
{noformat}
provider myserv {
...
};
{noformat}
Next, add a definition for each probe and the corresponding arguments. The following example defines the two probes discussed in [Choosing the Probe Points|#chp-usdt-1]. The first probe has two arguments, both of type {{string}}, and the second probe has no arguments. The D compiler converts two consecutive underscores ({{\-\-}}) in any probe name to a hyphen ({{\-}}).
{noformat}
provider myserv {
probe query__receive(string, string);
probe query__respond();
};
{noformat}
You should add stability attributes to your provider definition so that consumers of your probes understand the likelihood of change in future versions of your application. See [Chapter 39, Stability|Stability] for more information on the DTrace stability attributes. Stability attributes are defined as shown in the following example:
h6. {anchor:ex-myserv.d} Example: {{myserv.d}}: Statically Defined Application Probes
{noformat}
#pragma D attributes Evolving/Evolving/Common provider myserv provider
#pragma D attributes Private/Private/Unknown provider myserv module
#pragma D attributes Private/Private/Unknown provider myserv function
#pragma D attributes Evolving/Evolving/Common provider myserv name
#pragma D attributes Evolving/Evolving/Common provider myserv args
provider myserv {
probe query__receive(string, string);
probe query__respond();
};
{noformat}
[Top|#top]
h3. {anchor:chp-usdt-4} Adding Probes to Application Code
Now that you have defined your probes in a {{.d}} file, you need to augment your source code to indicate the locations that should trigger your probes. Consider the following example C application source code:
{noformat}
void
main_look(void)
{
...
query = wait_for_new_query();
process_query(query)
...
}
{noformat}
To add a probe site, add a reference to the {{DTRACE_PROBE()}} macro defined in {{<sys/sdt.h>}} as shown in the following example:
{noformat}
...
void
main_look(void)
{
...
query = wait_for_new_query();
DTRACE_PROBE2(myserv, query__receive, query->clientname, query->msg);
process_query(query)
...
}
{noformat}
The suffix {{2}} in the macro name {{DTRACE_PROBE2}} refers the number of arguments that are passed to the probe. The first two arguments to the probe macro are the provider name and probe name and must correspond to your D provider and probe definitions. The remaining macro arguments are the arguments assigned to the DTrace {{arg0..9}} variables when the probes fires.Your application source code can contain multiple references to the same provider and probe name. If multiple references to the same probe are present in your source code, any of the macro references will cause the probe to fire.
[Top|#top]
h3. {anchor:chp-usdt-5} Building Applications with Probes
You must augment the build process for your application to include the DTrace provider and probe definitions. A typical build process takes each source file and compiles it to create a corresponding object file. The compiled object files are then linked together to create the finished application binary, as shown in the following example:
{noformat}
cc -c src1.c
cc -c src2.c
...
cc -o myserv src1.o src2.o ...
{noformat}
To include DTrace probe definitions in your application, add appropriate Makefile rules to your build process to execute the {{dtrace}} command as shown in the following example:
{noformat}
cc -c src1.c
cc -c src2.c
...
dtrace -G -32 -s myserv.d src1.o src2.o ... |