https://github.com/bgamari/hs-usdt
A library for introducing USDT tracepoints into Haskell programs
https://github.com/bgamari/hs-usdt
Last synced: over 1 year ago
JSON representation
A library for introducing USDT tracepoints into Haskell programs
- Host: GitHub
- URL: https://github.com/bgamari/hs-usdt
- Owner: bgamari
- Created: 2022-04-08T19:31:05.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-12-08T15:47:02.000Z (over 2 years ago)
- Last Synced: 2025-04-06T13:17:21.560Z (over 1 year ago)
- Language: Haskell
- Size: 13.7 KB
- Stars: 5
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.mkd
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# 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
```
[mislink]: https://github.com/iovisor/bcc/issues/1528
## Example session
First build the project,
```bash
$ 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:
```bash
$ 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:
```bash
$ 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)
```