on-restart-benchmarks/tests/dtrace

Dynamic tracing in MiniZinc

MiniZinc has preliminary support for dynamic tracing. This allows developers to enable inserting custom tracing scripts at certain crucial points during execution without any the overhead when tracing is not required.

This tracing is supported through DTrace. DTrace is only available for MacOS and BSD. For Linux there is an alternative called SystemTap. SystemTap uses the same resources as DTrace, but uses different scripts.

DTrace

DTrace provides a library for dynamic tracing of events. This document describes the implementation of DTrace within the MiniZinc compiler. In particular, it focuses on how to use and extend the DTrace implementation within MiniZinc.

Executing DTrace scripts with MiniZinc

You can find various example DTrace scripts in tests/dtrace/. To run these scripts, you can use a command in the form of [script] -c "[command]". You need to use a MiniZinc compiler compiled with the DTrace to use DTrace.

You can also execute a script using the dtrace command. This is necessary if the script does not contain a "Shebang". You can do it using the following command: dtrace -s [script] -c "[command]".

MacOS 10.11+

MacOS El Capitan for the first time included "System Integrity Protection". This feature does not allow for all DTrace features to be used. This includes custom DTrace providers. To get around this problem, the following steps can be followed:

1. Boot your Mac into Recovery Mode.
2. Open the Terminal from the Utilities menu.
3. Then use the following commands:

csrutil clear # restore the default configuration first

csrutil enable --without dtrace # disable dtrace restrictions *only*

After completing these steps your Mac should be able to use DTrace after a restart. For more information visit the following article: link.

Writing scripts for DTrace with MiniZinc

The following paragraph will inform you on the MiniZinc provider and its probes for DTrace. We refer to the DTrace documentation for more information on the syntax and possibilities.

The MiniZinc provider for DTrace consists of DTrace probes implemented in the Runtime. A binary compiled with DTrace enabled will allow the user access to the information of the probes. You can find a list of all probes and their arguments in include/minizinc/support/dtrace_probes.d. The following is a toy example DTrace script:

pony$target:::gc-start
{
  @ = count();
}

END
{
  printa(@);
}

This script increases a counter every time the "GC Start" probe is fired and prints it result at the end. Note the way in which we access the probe. It consists of two parts: the first part is the provider and the second part, after ::: is the name of the probe. The provider is during runtime appended by the process ID. In this example we use the $target variable to find the process ID. Another option is to use pony*, but note that this could match many processes. The name of the probe are also different from the names in include/minizinc/support/dtrace_probes.d. In Dtrace scripts you have to replace the __ in the names by -.

To make these scripts executable, like the ones in the examples, we use the following "Shebang": #!/usr/bin/env dtrace -s. Extra options can be added to improve its functionality.

SystemTap

SystemTap is the Linux alternative to DTrace. Although DTrace is available for Linux the licensing and philosophical differences have caused Linux developers to create an alternative tracing framework that is compatible with the GPLv2, thus SystemTap was created. SystemTap and DTrace operate in a similar fashion but since then the frameworks have been developed independently. Complete SystemTap documentation can be found here

Requirements

• Linux Kernel with UPROBES or UTRACE.

If your Linux kernel is version 3.5 or higher, it already includes UPROBES. To verify that the current kernel supports UPROBES natively, run the following command:

# grep CONFIG_UPROBES /boot/config-`uname -r`

If the kernel supports the probes this will be the output:

CONFIG_UPROBES=y

If the kernel's version is prior to 3.5, SystemTap automatically builds the UPROBES module. However, you also need the UTRACE kernel extensions required by the SystemTap user-space probing to track various user-space events. This can be verified with this command:

# grep CONFIG_UTRACE /boot/config-`uname -r

If the < 3.5 kernel supports user tracing this will be the output:

CONFIG_UTRACE=y

Note: UTRACE does not exist on kernel versions > 3.5 and has been replaced by UPROBES

• SystemTap > 2.6

  You need the dtrace commandline tool to generate header and object files that are needed in the compilation and linking of MiniZinc compiler. This is required on Linux systems. At the time of writing this the version of SystemTap that these probes have been implemented and tested with is 2.6, on Debian 8 Stable. Later versions should work. Earlier versions might not work and must be tested independently. In debian based systems, SystemTap can be installed with apt-get

  ```
  $sudo apt-get install systemtap systemtap-sdt-dev
  ```
  

Executing SystemTap scripts with MiniZinc

You can find various example SystemTap scripts in tests/dtrace/. To run these scripts, a sample command would be of the form:

# stap [script path] -c "[command]"

NB: stap must be run as root (or sudo) since it compiles the SystemTap script into a loadable kernel module and loads it into the kernel when the stap script is running.

You need to use a PonyC compiler compiled with the DTrace support to use SystemTap.

Writing scripts for SystemTap in MiniZinc

SystemTap and DTrace use the same syntax for creating providers and thus we direct to the DTrace documentation for more information on the syntax and possibilities.

The MiniZinc provider for SystemTap consists of DTrace probes implemented in the Runtime. A binary compiled with DTrace enabled will allow the user access to the information of the probes, which work with SystemTap scripts. You can find a list of all probes and their arguments in include/minizinc/support/dtrace_probes.d. The following is a toy example of a SystemTap script:

global gc_passes

probe process.mark("gc-start")
{
  gc_passes <<< $arg1;
}

probe end
{
  printf("Total number of GC passes: %d\n", @count(gc_passes));
}

This simple example will hook into the executable that the -c parameter provides and searches for the probe named "gc-start". Once execution of the executable is started, the script increases a counter every time the "gc-start" probe is accessed and at the end of the run the results of the counter are printed

In SystemTap you can use the DTrace syntax of "gc-start" but you may also call them like they are in the include/minizinc/support/dtrace_probes.d file, "gc__start".

All available probes in an executable can be listed like this:

# stap -L 'process("<name_and_path_of_executable>").mark("*")'

This is useful to confirm that probes are ready to be hooked in.

Extending dynamic tracing in MiniZinc

You can extend the dynamic tracing implementation by adding more probes or extra information to existing probes. All probes are defined in include/minizinc/support/dtrace_probes.d. Usually their names of their module and the event that triggers them. To install Probes in C use the macros defined in include/minizinc/support/dtrace.h. To fire a probe in the C code use the macro DTRACEx; where x is the number of arguments of the probe. There is also a macro DTRACE_ENABLED; its use allows for code to be only executed when a probe is enabled.

Adding a probe

The first step to add a probe is to add its definition into include/minizinc/support/dtrace_probes.d. We have split the names of the probes into two parts: its category and the specific event. The name is split using __. We also add a comment to a probe explaining when it's fired and the information contained in its arguments.

After adding the probe, we use it in the C code using the macros. Note that the split in the name is only a single underscore in the C code. The name of the probe should also be capitalised. We can call the probe defined as gc__start using the statement DTRACE1(GC_START, scheduler). In this statement scheduler is the data used as the first argument.

Then once the probe has been placed in all the appropriate places, we are ready to recompile. Make sure to use the DTrace flag while compiling. Recompiling will create the appropriate files using the system installation of DTrace.

Extending a probe

We can extend a probe by adding an extra argument to the probe. Like adding a probe, the probe definition needs to be appended in include/minizinc/support/dtrace_probes.d Note that this extra information needs to be available everywhere the probe is used.

Once you've added the argument, you need to change all instances where the probe is in use. Note that you have to both add the new argument and change the DTRACE macro. Then you can recompile the MiniZinc compiler to use your new arguments.

Do not forget that if you change the order of the arguments for any of the existing nodes, you also need to change their usage in the example scripts.