Next

	Red Hat Enterprise Linux 6 Essentials eBook now available in PDF and ePub formats for only $9.99 RHEL 6 Essentials contains 40 chapters and over 250 pages.

Red Hat Enterprise Linux 6

SystemTap Tapset Reference

For SystemTap in Red Hat Enterprise Linux 6

Edition 0

Red Hat Enterprise Linux Documentation

William Cohen

Engineering Services and Operations Performance Tools

wcohen@redhat.com

Don Domingo

Engineering Services and Operations Content Services

ddomingo@redhat.com

Legal Notice

This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

For more details see the file COPYING in the source distribution of Linux.

Abstract

The Tapset Reference Guide describes the most common tapset definitions users can apply to SystemTap scripts. All included tapsets documented in this guide are current as of the latest upstream version of SystemTap.

Preface

1. Document Conventions

1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings

2. Getting Help and Giving Feedback

2.1. Do You Need Help?
2.2. We Need Feedback!

1. Introduction

1.1. Documentation Goals

2. Tapset Development Guidelines

2.1. Writing Good Tapsets

2.2. Elements of a Tapset

2.2.1. Tapset Files
2.2.2. Namespace
2.2.3. Comments and Documentation

3. Context Functions

function::print_regs — Print a register dump.
function::execname — Returns the execname of a target process (or group of processes).
function::pid — Returns the ID of a target process.
function::tid — Returns the thread ID of a target process.
function::ppid — Returns the process ID of a target process's parent process.
function::pgrp — Returns the process group ID of the current process.
function::sid — Returns the session ID of the current process.
function::pexecname — Returns the execname of a target process's parent process.
function::gid — Returns the group ID of a target process.
function::egid — Returns the effective gid of a target process.
function::uid — Returns the user ID of a target process.
function::euid — Return the effective uid of a target process.
function::is_myproc — Determines if the current probe point has occurred in the user's own process.
function::cpu — Returns the current cpu number.
function::pp — Returns the active probe point.
function::registers_valid — Determines validity of register and u_register in current context.
function::user_mode — Determines if probe point occurs in user-mode.
function::is_return — Whether the current probe context is a return probe.
function::target — Return the process ID of the target process.
function::module_name — The module name of the current script.
function::stp_pid — The process id of the stapio process.
function::stack_size — Return the size of the kernel stack.
function::stack_used — Returns the amount of kernel stack used.
function::stack_unused — Returns the amount of kernel stack currently available.
function::uaddr — User space address of current running task. EXPERIMENTAL.
function::cmdline_args — Fetch command line arguments from current process
function::cmdline_arg — Fetch a command line argument.
function::cmdline_str — Fetch all command line arguments from current process
function::env_var — Fetch environment variable from current process
function::print_stack — Print out kernel stack from string.
function::sprint_stack — Return stack for kernel addresses from string. EXPERIMENTAL!
function::probefunc — Return the probe point's function name, if known.
function::probemod — Return the probe point's kernel module name.
function::modname — Return the kernel module name loaded at the address.
function::symname — Return the kernel symbol associated with the given address.
function::symdata — Return the kernel symbol and module offset for the address.
function::usymname — Return the symbol of an address in the current task. EXPERIMENTAL!
function::usymdata — Return the symbol and module offset of an address. EXPERIMENTAL!
function::print_ustack — Print out stack for the current task from string. EXPERIMENTAL!
function::sprint_ustack — Return stack for the current task from string. EXPERIMENTAL!
function::print_backtrace — Print stack back trace
function::sprint_backtrace — Return stack back trace as string. EXPERIMENTAL!
function::backtrace — Hex backtrace of current stack
function::task_backtrace — Hex backtrace of an arbitrary task
function::caller — Return name and address of calling function
function::caller_addr — Return caller address
function::print_ubacktrace — Print stack back trace for current task. EXPERIMENTAL!
function::sprint_ubacktrace — Return stack back trace for current task as string. EXPERIMENTAL!
function::print_ubacktrace_brief — Print stack back trace for current task. EXPERIMENTAL!
function::ubacktrace — Hex backtrace of current task stack. EXPERIMENTAL!
function::task_current — The current task_struct of the current task.
function::task_parent — The task_struct of the parent task.
function::task_state — The state of the task.
function::task_execname — The name of the task.
function::task_pid — The process identifier of the task.
function::pid2task — The task_struct of the given process identifier.
function::pid2execname — The name of the given process identifier.
function::task_tid — The thread identifier of the task.
function::task_gid — The group identifier of the task.
function::task_egid — The effective group identifier of the task.
function::task_uid — The user identifier of the task.
function::task_euid — The effective user identifier of the task.
function::task_prio — The priority value of the task.
function::task_nice — The nice value of the task.
function::task_cpu — The scheduled cpu of the task.
function::task_open_file_handles — The number of open files of the task.
function::task_max_file_handles — The max number of open files for the task.
function::pn — Returns the active probe name.

4. Timestamp Functions

function::get_cycles — Processor cycle count.
function::gettimeofday_ns — Number of nanoseconds since UNIX epoch.
function::gettimeofday_us — Number of microseconds since UNIX epoch.
function::gettimeofday_ms — Number of milliseconds since UNIX epoch.
function::gettimeofday_s — Number of seconds since UNIX epoch.

5. Time string utility function

function::ctime — Convert seconds since epoch into human readable date/time string.

6. Memory Tapset

function::vm_fault_contains — Test return value for page fault reason
probe::vm.pagefault — Records that a page fault occurred.
probe::vm.pagefault.return — Indicates what type of fault occurred.
function::addr_to_node — Returns which node a given address belongs to within a NUMA system.
probe::vm.write_shared — Attempts at writing to a shared page.
probe::vm.write_shared_copy — Page copy for shared page write.
probe::vm.mmap — Fires when an mmap is requested.
probe::vm.munmap — Fires when an munmap is requested.
probe::vm.brk — Fires when a brk is requested (i.e. the heap will be resized).
probe::vm.oom_kill — Fires when a thread is selected for termination by the OOM killer.
probe::vm.kmalloc — Fires when kmalloc is requested.
probe::vm.kmem_cache_alloc — Fires when \
probe::vm.kmalloc_node — Fires when kmalloc_node is requested.
probe::vm.kmem_cache_alloc_node — Fires when \
probe::vm.kfree — Fires when kfree is requested.
probe::vm.kmem_cache_free — Fires when \
function::proc_mem_size — Total program virtual memory size in pages
function::proc_mem_size_pid — Total program virtual memory size in pages
function::proc_mem_rss — Program resident set size in pages
function::proc_mem_rss_pid — Program resident set size in pages
function::proc_mem_shr — Program shared pages (from shared mappings)
function::proc_mem_shr_pid — Program shared pages (from shared mappings)
function::proc_mem_txt — Program text (code) size in pages
function::proc_mem_txt_pid — Program text (code) size in pages
function::proc_mem_data — Program data size (data + stack) in pages
function::proc_mem_data_pid — Program data size (data + stack) in pages
function::mem_page_size — Number of bytes in a page for this architecture
function::bytes_to_string — Human readable string for given bytes
function::pages_to_string — Turns pages into a human readable string
function::proc_mem_string — Human readable string of current proc memory usage
function::proc_mem_string_pid — Human readable string of process memory usage

7. Task Time Tapset

function::task_utime — User time of the current task
function::task_utime_tid — User time of the given task
function::task_stime — System time of the current task
function::task_stime_tid — System time of the given task
function::cputime_to_msecs — Translates the given cputime into milliseconds
function::msecs_to_string — Human readable string for given milliseconds
function::cputime_to_string — Human readable string for given cputime
function::task_time_string — Human readable string of task time usage
function::task_time_string_tid — Human readable string of task time usage

8. IO Scheduler and block IO Tapset

probe::ioscheduler.elv_next_request — Fires when a request is retrieved from the request queue
probe::ioscheduler.elv_next_request.return — Fires when a request retrieval issues a return signal
probe::ioscheduler.elv_completed_request — Fires when a request is completed
probe::ioscheduler.elv_add_request.kp — kprobe based probe to indicate that a request was added to the request queue
probe::ioscheduler.elv_add_request.tp — tracepoint based probe to indicate a request is added to the request queue.
probe::ioscheduler.elv_add_request — probe to indicate request is added to the request queue.
probe::ioscheduler_trace.elv_completed_request — Fires when a request is
probe::ioscheduler_trace.elv_issue_request — Fires when a request is
probe::ioscheduler_trace.elv_requeue_request — Fires when a request is
probe::ioscheduler_trace.elv_abort_request — Fires when a request is aborted.
probe::ioscheduler_trace.plug — Fires when a request queue is plugged;
probe::ioscheduler_trace.unplug_io — Fires when a request queue is unplugged;
probe::ioscheduler_trace.unplug_timer — Fires when unplug timer associated
probe::ioblock.request — Fires whenever making a generic block I/O request.
probe::ioblock.end — Fires whenever a block I/O transfer is complete.
probe::ioblock_trace.bounce — Fires whenever a buffer bounce is needed for at least one page of a block IO request.
probe::ioblock_trace.request — Fires just as a generic block I/O request is created for a bio.
probe::ioblock_trace.end — Fires whenever a block I/O transfer is complete.

9. SCSI Tapset

probe::scsi.ioentry — Prepares a SCSI mid-layer request
probe::scsi.iodispatching — SCSI mid-layer dispatched low-level SCSI command
probe::scsi.iodone — SCSI command completed by low level driver and enqueued into the done queue.
probe::scsi.iocompleted — SCSI mid-layer running the completion processing for block device I/O requests
probe::scsi.ioexecute — Create mid-layer SCSI request and wait for the result
probe::scsi.set_state — Order SCSI device state change

10. TTY Tapset

probe::tty.open — Called when a tty is opened
probe::tty.release — Called when the tty is closed
probe::tty.resize — Called when a terminal resize happens
probe::tty.ioctl — called when a ioctl is request to the tty
probe::tty.init — Called when a tty is being initalized
probe::tty.register — Called when a tty device is registred
probe::tty.unregister — Called when a tty device is being unregistered
probe::tty.poll — Called when a tty device is being polled
probe::tty.receive — called when a tty receives a message
probe::tty.write — write to the tty line
probe::tty.read — called when a tty line will be read

11. Networking Tapset

probe::netdev.receive — Data received from network device.
probe::netdev.transmit — Network device transmitting buffer
probe::netdev.change_mtu — Called when the netdev MTU is changed
probe::netdev.open — Called when the device is opened
probe::netdev.close — Called when the device is closed
probe::netdev.hard_transmit — Called when the devices is going to TX (hard)
probe::netdev.rx — Called when the device is going to receive a packet
probe::netdev.change_rx_flag — Called when the device RX flag will be changed
probe::netdev.set_promiscuity — Called when the device enters/leaves promiscuity
probe::netdev.ioctl — Called when the device suffers an IOCTL
probe::netdev.register — Called when the device is registered
probe::netdev.unregister — Called when the device is being unregistered
probe::netdev.get_stats — Called when someone asks the device statistics
probe::netdev.change_mac — Called when the netdev_name has the MAC changed
probe::tcp.sendmsg — Sending a tcp message
probe::tcp.sendmsg.return — Sending TCP message is done
probe::tcp.recvmsg — Receiving TCP message
probe::tcp.recvmsg.return — Receiving TCP message complete
probe::tcp.disconnect — TCP socket disconnection
probe::tcp.disconnect.return — TCP socket disconnection complete
probe::tcp.setsockopt — Call to setsockopt
probe::tcp.setsockopt.return — Return from setsockopt
probe::tcp.receive — Called when a TCP packet is received
probe::udp.sendmsg — Fires whenever a process sends a UDP message
probe::udp.sendmsg.return — Fires whenever an attempt to send a UDP message is completed
probe::udp.recvmsg — Fires whenever a UDP message is received
probe::udp.recvmsg.return — Fires whenever an attempt to receive a UDP message received is completed
probe::udp.disconnect — Fires when a process requests for a UDP disconnection
probe::udp.disconnect.return — UDP has been disconnected successfully
function::ip_ntop — returns a string representation from an integer IP number

12. Socket Tapset

probe::socket.send — Message sent on a socket.
probe::socket.receive — Message received on a socket.
probe::socket.sendmsg — Message is currently being sent on a socket.
probe::socket.sendmsg.return — Return from socket.sendmsg.
probe::socket.recvmsg — Message being received on socket
probe::socket.recvmsg.return — Return from Message being received on socket
probe::socket.aio_write — Message send via sock_aio_write
probe::socket.aio_write.return — Conclusion of message send via sock_aio_write
probe::socket.aio_read — Receiving message via sock_aio_read
probe::socket.aio_read.return — Conclusion of message received via sock_aio_read
probe::socket.writev — Message sent via socket_writev
probe::socket.writev.return — Conclusion of message sent via socket_writev
probe::socket.readv — Receiving a message via sock_readv
probe::socket.readv.return — Conclusion of receiving a message via sock_readv
probe::socket.create — Creation of a socket
probe::socket.create.return — Return from Creation of a socket
probe::socket.close — Close a socket
probe::socket.close.return — Return from closing a socket
function::sock_prot_num2str — Given a protocol number, return a string representation.
function::sock_prot_str2num — Given a protocol name (string), return the corresponding protocol number.
function::sock_fam_num2str — Given a protocol family number, return a string representation.
function::sock_fam_str2num — Given a protocol family name (string), return the corresponding
function::sock_state_num2str — Given a socket state number, return a string representation.
function::sock_state_str2num — Given a socket state string, return the corresponding state number.

13. Kernel Process Tapset

probe::kprocess.create — Fires whenever a new process is successfully created
probe::kprocess.start — Starting new process
probe::kprocess.exec — Attempt to exec to a new program
probe::kprocess.exec_complete — Return from exec to a new program
probe::kprocess.exit — Exit from process
probe::kprocess.release — Process released

14. Signal Tapset

probe::signal.send — Signal being sent to a process
probe::signal.send.return — Signal being sent to a process completed
probe::signal.checkperm — Check being performed on a sent signal
probe::signal.checkperm.return — Check performed on a sent signal completed
probe::signal.wakeup — Sleeping process being wakened for signal
probe::signal.check_ignored — Checking to see signal is ignored
probe::signal.check_ignored.return — Check to see signal is ignored completed
probe::signal.force_segv — Forcing send of SIGSEGV
probe::signal.force_segv.return — Forcing send of SIGSEGV complete
probe::signal.syskill — Sending kill signal to a process
probe::signal.syskill.return — Sending kill signal completed
probe::signal.sys_tkill — Sending a kill signal to a thread
probe::signal.systkill.return — Sending kill signal to a thread completed
probe::signal.sys_tgkill — Sending kill signal to a thread group
probe::signal.sys_tgkill.return — Sending kill signal to a thread group completed
probe::signal.send_sig_queue — Queuing a signal to a process
probe::signal.send_sig_queue.return — Queuing a signal to a process completed
probe::signal.pending — Examining pending signal
probe::signal.pending.return — Examination of pending signal completed
probe::signal.handle — Signal handler being invoked
probe::signal.handle.return — Signal handler invocation completed
probe::signal.do_action — Examining or changing a signal action
probe::signal.do_action.return — Examining or changing a signal action completed
probe::signal.procmask — Examining or changing blocked signals
probe::signal.procmask.return — Examining or changing blocked signals completed
probe::signal.flush — Flushing all pending signals for a task

15. Directory-entry (dentry) Tapset

function::d_name — get the dirent name
function::reverse_path_walk — get the full dirent path
function::task_dentry_path — get the full dentry path
function::d_path — get the full nameidata path

16. Logging Tapset

function::log — Send a line to the common trace buffer.
function::warn — Send a line to the warning stream.
function::exit — Start shutting down probing script.
function::error — Send an error message.
function::ftrace — Send a message to the ftrace ring-buffer.

17. Random functions Tapset

function::randint — Return a random number between [0,n)

18. String and data retrieving functions Tapset

function::kernel_string — Retrieves string from kernel memory.
function::kernel_string2 — Retrieves string from kernel memory with alternative error string.
function::kernel_string_n — Retrieves string of given length from kernel memory.
function::kernel_long — Retrieves a long value stored in kernel memory.
function::kernel_int — Retrieves an int value stored in kernel memory.
function::kernel_short — Retrieves a short value stored in kernel memory.
function::kernel_char — Retrieves a char value stored in kernel memory.
function::kernel_pointer — Retrieves a pointer value stored in kernel memory.
function::user_string — Retrieves string from user space.
function::user_string2 — Retrieves string from user space with alternative error string.
function::user_string_warn — Retrieves string from user space.
function::user_string_quoted — Retrieves and quotes string from user space.
function::user_string_n — Retrieves string of given length from user space.
function::user_string_n2 — Retrieves string of given length from user space.
function::user_string_n_warn — Retrieves string from user space.
function::user_string_n_quoted — Retrieves and quotes string from user space.
function::user_short — Retrieves a short value stored in user space.
function::user_short_warn — Retrieves a short value stored in user space.
function::user_int — Retrieves an int value stored in user space.
function::user_int_warn — Retrieves an int value stored in user space.
function::user_long — Retrieves a long value stored in user space.
function::user_long_warn — Retrieves a long value stored in user space.
function::user_char — Retrieves a char value stored in user space.
function::user_char_warn — Retrieves a char value stored in user space.

19. A collection of standard string functions

function::strlen — Returns the length of a string.
function::substr — Returns a substring.
function::stringat — Returns the char at a given position in the string.
function::isinstr — Returns whether a string is a substring of another string.
function::text_str — Escape any non-printable chars in a string.
function::text_strn — Escape any non-printable chars in a string.
function::tokenize — Return the next non-empty token in a string.
function::str_replace — str_replace Replaces all instances of a substring with another.
function::strtol — strtol - Convert a string to a long.
function::isdigit — Checks for a digit.

20. Utility functions for using ansi control chars in logs

function::ansi_clear_screen — Move cursor to top left and clear screen.
function::ansi_set_color — Set the ansi Select Graphic Rendition mode.
function::ansi_set_color2 — Set the ansi Select Graphic Rendition mode.
function::ansi_set_color3 — Set the ansi Select Graphic Rendition mode.
function::ansi_reset_color — Resets Select Graphic Rendition mode.
function::ansi_new_line — Move cursor to new line.
function::ansi_cursor_move — Move cursor to new coordinates.
function::ansi_cursor_hide — Hides the cursor.
function::ansi_cursor_save — Saves the cursor position.
function::ansi_cursor_restore — Restores a previously saved cursor position.
function::ansi_cursor_show — Shows the cursor.

NextPreface