<!--
%CopyrightBegin%

SPDX-License-Identifier: Apache-2.0

Copyright Ericsson AB 2023-2025. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

%CopyrightEnd%
-->
# SystemTap and Erlang/OTP

## Introduction

SystemTap is DTrace for Linux. In fact Erlang's SystemTap support is built using
SystemTap's DTrace compatibility's layer. For an introduction to Erlang DTrace
support read [$ERL_TOP/HOWTO/DTRACE.md](dtrace.md).

## Requisites

- Linux Kernel with UTRACE support

  check for UTRACE support in your current kernel:

  ```text
  # grep CONFIG_UTRACE /boot/config-`uname -r`
  CONFIG_UTRACE=y
  ```

  Fedora 16 is known to contain UTRACE, for most other Linux distributions a
  custom build kernel will be required. Check Fedora's SystemTap documentation
  for additional required packages (e.g. Kernel Debug Symbols)

- SystemTap > 1.6

  A the time of writing this, the latest released version of SystemTap is
  version 1.6. Erlang's DTrace support requires a MACRO that was introduced
  after that release. So either get a newer release or build SystemTap from git
  yourself (see: http://sourceware.org/systemtap/getinvolved.html)

## Building Erlang

Configure and build Erlang with SystemTap support:

```text
# ./configure --with-dynamic-trace=systemtap + whatever args you need
# make
```

## Testing

SystemTap, unlike DTrace, needs to know what binary it is tracing and has to be
able to read that binary before it starts tracing. Your probe script therefore
has to reference the correct beam emulator and stap needs to be able to find
that binary. The examples are written for "beam", but other versions such as
"beam.smp" or "beam.debug.smp" might exist (depending on your configuration).
Make sure you either specify the full the path of the binary in the probe or
your "beam" binary is in the search path.

All available probes can be listed like this:

```text
# stap -L 'process("beam").mark("*")'
```

or:

```text
# PATH=/path/to/beam:$PATH stap -L 'process("beam").mark("*")'
```

Probes in the dtrace.so NIF library like this:

```text
# PATH=/path/to/dtrace/priv/lib:$PATH stap -L 'process("dtrace.so").mark("*")'
```

## Running SystemTap scripts

Adjust the process("beam") reference to your beam version and attach the script
to a running "beam" instance:

```text
# stap /path/to/probe/script/port1.systemtap -x <pid of beam>
```
