hs-usdt - A library for embedding of tracepoints in Haskell programs

This library offers a set of TemplateHaskell utilities for embedding USDT tracepoints in Haskell programs. It has been tested on Linux with Systemtap's dtrace implementation.

Note that convenient use with perf executables must be built with ld's --build-id flag. This can be achieved by adding the following to your .cabal or cabal.project file:

ghc-options: -optl-Wl,--build-id

Caveats

Unfortunately, the default linker used by most GHC installations, ld.gold appears to mislink USDT probes. Consequently, it is necessary to instead use ld.bfd or ld.lld. This can be achieved by adding the following to your cabal file:

ghc-options: -optl-fuse-ld=bfd

Example session

First build the project,

$ nix shell nixpkgs#linuxPackages.systemtap
$ nix build nixpkgs#libsystemtap
$ echo "package hs-usdt" > cabal.project.local
$ echo "  extra-include-dirs: $(realpath ./result)/include" >> cabal.project.local
$ echo "  ghc-options: -optl-Wl,--build-id -optl-fuse-ld=bfd" >> cabal.project.local
$ cabal build
$ exe="$(cabal list-bin hs_usdt_test)"

Now let perf know about the executable's tracepoints:

$ perf buildid-cache --add "$exe"
$ perf probe -x "$exe" sdt_hs_usdt__Main:tp1
$ perf list | grep hs_usdt
  sdt_hs_usdt__Main:tp1                              [Tracepoint event]
  sdt_hs_usdt__Main:tp1                              [SDT event]

Now we can run the executable under perf, e.g. recording tracepoint events:

$ perf record -e sdt_hs_usdt__Main:tp1 "$exe"
Hello, Haskell!
[ perf record: Woken up 1 times to write data ]
[ perf record: Captured and wrote 0.043 MB perf.data (2 samples) ]
$ perf script
    hs_usdt_test 166810 [015] 191748.282102: sdt_hs_usdt__Main:tp1: (403354)
    hs_usdt_test 166810 [015] 191748.282104: sdt_hs_usdt__Main:tp1: (403354)