SystemTap Tapset Reference Manual

SystemTap

Hackers

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.


Table of Contents

1. Introduction
Tapset Name Format
2. 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.
3. 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.
4. Time string utility function
function::ctime - Convert seconds since epoch into human readable date/time string.
5. 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
6. 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
7. 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.
8. 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
9. 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
10. 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
11. 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.
12. 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
13. 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
14. Directory-entry (dentry) Tapset
function::d_name - get the dirent name
function::reverse_path_walk - get the full dirent path
function::d_path - get the full nameidata path
15. 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.
16. Random functions Tapset
function::randint - Return a random number between [0,n)
17. 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.
18. 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.
19. 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.