dtrace.md

BUILDING CODE CONTAINING USDT PROBES
     The process of adding USDT probes to code is slightly different than documented in the Solaris Dynamic
     Tracing Guide.  The steps for adding probes are as follows:

     1.   Name the provider and specify its probes, using the following form:

          provider Example {
                  probe increment(int);
          };

          This defines the Example provider with one probe, increment, that takes a single int argument.
          Providers can define multiple probes and probes can take multiple arguments.

     2.   Process the provider description into a header file.

          The provider description must be converted into a form usable by ObjC/C/C++ code.  The dtrace com-
          mand should be invoked with the -h option to do this.

          dtrace -h -s exampleProvider.d

          This will generate a header file named exampleProvider.h

     3.   Add probe invocations to the application.

          For each probe defined in the provider, the provider.h file will contain two macros.  The naming
          is as follows:

          PROVIDER_PROBENAME()
          PROVIDER_PROBENAME_ENABLED()

          In the Example provider, the increment probe becomes:

          EXAMPLE_INCREMENT()
          EXAMPLE_INCREMENT_ENABLED()

          Place a macro invocation in the code at each site to be traced.  If the arguments passed to a
          probe are expensive to calculate, you may guard the probe placement like this:

          if (EXAMPLE_INCREMENT_ENABLED()) {
                  argument = /* Expensive argument calculation code here */;
                  EXAMPLE_INCREMENT(argument);
          };

          The if test will only succeed when the increment probe is active.

     4.   Compile and link your program normally.  No additional compiler or linker flags are required.