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
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
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)