# Understanding How SystemTap Works

Short summary; probes, handlers, events

SystemTap allows users to write and reuse simple scripts to deeply examine the activities of a running Linux system. These scripts can be designed to extract data, filter it, and summarize it quickly (and safely), enabling the diagnosis of complex performance (or even functional) problems.

The essential idea behind a SystemTap script is to name events, and to give them handlers. When SystemTap runs the script, SystemTap monitors for the event; once the event occurs, the Linux kernel then runs the handler as a quick sub-routine, then resumes.

There are several kind of events; entering/exiting a function, timer expiration, session termination, etc. A handler is a series of script language statements that specify the work to be done whenever the event occurs. This work normally includes extracting data from the event context, storing them into internal variables, and printing results.

## Architecture

** add diagram, describe architecture, enumerate common tools ** architecture diagram must be simpler, if at all included ** add design advantages? e.g. "building kmods on-the-fly allows safer execution of script etc etc"

A SystemTap session begins when you run a SystemTap script. This session occurs in the following fashion:

SystemTap Session

- First, SystemTap checks the script against the existing tapset library (normally in `/usr/share/systemtap/tapset/` for any tapsets used. SystemTap will then substitute any located tapsets with their corresponding definitions in the tapset library.

- SystemTap then translates the script to C, running the system C compiler to create a kernel module from it. The tools that perform this step are contained in the `systemtap` package (refer to for more information).

- SystemTap loads the module, then enables all the probes (events and handlers) in the script. The `staprun` in the `systemtap-runtime` package (refer to for more information) provides this functionality.

- As the events occur, their corresponding handlers are executed.

- Once the SystemTap session is terminated, the probes are disabled, and the kernel module is unloaded.

Understanding How SystemTap Works SystemTap sessions
SystemTap sessions
sessions, SystemTap

This sequence is driven from a single command-line program: `stap`. This program is SystemTap's main front-end tool. For more information about `stap`, refer to `man stap` (once SystemTap is properly installed on your machine).

Understanding How SystemTap Works architecture
architecture of SystemTap
SystemTap architecture

## Tapsets

definition, significance, difference with stap scripts (previous section), library of tapsets in system: location

Tapsets are scripts that form a library of pre-written probes and functions to be used in SystemTap scripts. When a user runs a SystemTap script, SystemTap checks the script's probe events and handlers against the tapset library; SystemTap then loads the corresponding probes and functions before translating the script to C (refer to for information on what transpires in a SystemTap session).

Like SystemTap scripts, tapsets use the file name extension `.stp`. The standard library of tapsets is located in `/usr/share/systemtap/tapset/` by default. However, unlike SystemTap scripts, tapsets are not meant for direct execution; rather, they constitute the library from which other scripts can pull definitions.

The tapset library is an abstraction layer designed to make it easier for users to define events and functions. Tapsets provide useful aliases for functions that users may want to specify as an event; knowing the proper alias to use is, for the most part, easier than remembering specific kernel functions that might vary between kernel versions.

Several handlers and functions in and are defined in tapsets. For example, `thread_indent()` is defined in `indent.stp`.

any other details to be included? i dont want to dwell too long here, though, since IMHO tapset development is beyond the scope of this "beginner's guide"
Tapsets definition of
Understanding How SystemTap Works
Understanding How SystemTap Works events and handlers
events and handlers
handlers and events
Understanding How SystemTap Works event types
event types Understanding How SystemTap Works