Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

2.2. Elements of a Tapset

The following sections describe the most important aspects of writing a tapset. Most of the content herein is suitable for developers who wish to contribute to SystemTap's upstream library of tapsets.

2.2.1. Tapset Files
Copy link

Tapset files are stored in src/tapset/ of the SystemTap GIT directory. Most tapset files are kept at that level. If you have code that only works with a specific architecture or kernel version, you may choose to put your tapset in the appropriate subdirectory.
Installed tapsets are located in /usr/share/systemtap/tapset/ or /usr/local/share/systemtap/tapset.
Personal tapsets can be stored anywhere. However, to ensure that SystemTap can use them, use -I tapset_directory to specify their location when invoking stap.

2.2.2. Namespace
Copy link

Probe alias names should take the form tapset_name.probe_name. For example, the probe for sending a signal could be named signal.send.
Global symbol names (probes, functions, and variables) should be unique accross all tapsets. This helps avoid namespace collisions in scripts that use multiple tapsets. To ensure this, use tapset-specific prefixes in your global symbols.
Internal symbol names should be prefixed with an underscore (_).

2.2.3. Comments and Documentation
Copy link

All probes and functions should include comment blocks that describe their purpose, the data they provide, and the context in which they run (e.g. interrupt, process, etc). Use comments in areas where your intent may not be clear from reading the code.
Note that specially-formatted comments are automatically extracted from most tapsets and included in this guide. This helps ensure that tapset contributors can write their tapset and document it in the same place. The specified format for documenting tapsets is as follows: 
/**
 * probe tapset.name - Short summary of what the tapset does.
 * @argument: Explanation of argument.
 * @argument2: Explanation of argument2. Probes can have multiple arguments.
 *
 * Context:
 * A brief explanation of the tapset context. 
 * Note that the context should only be 1 paragraph short.
 *
 * Text that will appear under "Description."
 *
 * A new paragraph that will also appear under the heading "Description".
 *
 * Header:
 * A paragraph that will appear under the heading "Header".
 **/
Copy to Clipboard Toggle word wrap
For example: 
/**
 * probe vm.write_shared_copy- Page copy for shared page write.
 * @address: The address of the shared write.
 * @zero: Boolean indicating whether it is a zero page
 *         (can do a clear instead of a copy).
 *
 * Context:
 *  The process attempting the write.
 *
 *  Fires when a write to a shared page requires a page copy.  This is
 *  always preceded by a vm.shared_write.
 **/
Copy to Clipboard Toggle word wrap
To override the automatically-generated Synopsis content, use: 
 * Synopsis:
 * New Synopsis string
 *
Copy to Clipboard Toggle word wrap
For example: 
/**
 * probe signal.handle - Fires when the signal handler is invoked
 * @sig: The signal number that invoked the signal handler
 *
 * Synopsis:
 * <programlisting>static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka,
 * sigset_t *oldset, struct pt_regs * regs)</programlisting>
 */
Copy to Clipboard Toggle word wrap
It is recommended that you use the <programlisting> tag in this instance, since overriding the Synopsis content of an entry does not automatically form the necessary tags.
For the purposes of improving the DocBook XML output of your comments, you can also use the following XML tags in your comments:
  • command
  • emphasis
  • programlisting
  • remark (tagged strings will appear in Publican beta builds of the document)
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat