Summary of Contents for Red Hat ENTERPRISE LINUX 5.4 - SYSTEMTAP TAPSET
Page 1
Red Hat Enterprise Linux 5.4 SystemTap Tapset Reference For SystemTap in Red Hat Enterprise Linux 5 William Cohen Don Domingo...
Page 2
Red Hat Enterprise Linux 5.4 SystemTap Tapset Reference For SystemTap in Red Hat Enterprise Linux 5 Edition 1.0 Author William Cohen wcohen@redhat.com Author Don Domingo ddomingo@redhat.com 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.
Preface 1. Document Conventions This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information. Liberation Fonts In PDF and paper editions, this manual uses typefaces drawn from the set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed.
Preface Choose System > Preferences > Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
Notes and Warnings Output sent to a terminal is set in Mono-spaced Roman and presented thus: books Desktop documentation drafts photos stuff books_tests Desktop1 downloads images notes scripts svgs Source-code listings are also set in Mono-spaced Roman but are presented and highlighted as follows: package org.jboss.book.jca.ex1;...
2. We Need Feedback! If you find a typographical error in this manual, or if you have thought of a way to make this manual http://bugzilla.redhat.com/ better, we would love to hear from you! Please submit a report in Bugzilla: bugzilla/ against the product Red_Hat_Enterprise_Linux.
Chapter 1. Introduction SystemTap provides free software (GPL) infrastructure to simplify the gathering of information about the running Linux system. This assists diagnosis of a performance or functional problem. SystemTap eliminates the need for the developer to go through the tedious and disruptive instrument, recompile, install, and reboot sequence that may be otherwise required to collect data.
Chapter 2. Tapset Development Guidelines This chapter describes the upstream guidelines on proper tapset documentation. It also contains information on how to properly document your tapsets, to ensure that they are properly defined in this guide. 2.1. Writing Good Tapsets The first step to writing good tapsets is to create a simple model of your subject area.
Chapter 2. Tapset Development Guidelines kernel version or architecture dependencies are unavoidable, use preprocessor conditionals (see the stap(1) man page for details). Fill in the probe bodies with the key data available at the probe points. Function entry probes can access the entry parameters specified to the function, while exit probes can access the entry parameters and the return value.
Comments and Documentation Internal symbol names should be prefixed with an underscore (_). 2.2.3. Comments and Documentation 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.
Page 16
Chapter 2. Tapset Development Guidelines * New Synopsis string 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>...
Chapter 3. Context Functions The context functions provide additional information about where an event occurred. These functions can provide information such as a backtrace to where the event occured and the current register values for the processor. Name print_regs — Print a register dump. Synopsis function print_regs() Arguments...
Chapter 3. Context Functions Synopsis function tid:long() Arguments None Name ppid — Returns the process ID of a target process's parent process. Synopsis function ppid:long() Arguments None Name pgrp — Returns the process group ID of the current process. Synopsis function pgrp:long() Arguments None...
Description The session ID of a process is the process group ID of the session leader. Session ID is stored in the signal_struct since Kernel 2.6.0. Name pexecname — Returns the execname of a target process's parent process. Synopsis function pexecname:string() Arguments None Name...
Chapter 3. Context Functions Synopsis function uid:long() Arguments None Name euid — Return the effective uid of a target process. Synopsis function euid:long() Arguments None Name cpu — Returns the current cpu number. Synopsis function cpu:long() Arguments None Name pp — Return the probe point associated with the currently running probe handler, Synopsis function pp:string() Arguments...
Description including alias and wildcard expansion effects Context The current probe point. Name registers_valid — Determines validity of register and u_register in current context. Synopsis function registers_valid:long() Arguments None Description Return 1 if register and u_register can be used in the current context, or 0 otherwise. For example, registers_valid returns 0 when called from a begin or end probe.
Chapter 3. Context Functions Synopsis function is_return:long() Arguments None Description Return 1 if the probe point is a return probe. Deprecated. Name target — Return the process ID of the target process. Synopsis function target:long() Arguments None Name stack_size — Return the size of the kernel stack. Synopsis function stack_size:long() Arguments...
function stack_used:long() Arguments None Description Determines how many bytes are currently used in the kernel stack. Name stack_unused — Returns the amount of kernel stack currently available. Synopsis function stack_unused:long() Arguments None Description Determines how many bytes are currently available in the kernel stack. Name uaddr —...
Chapter 3. Context Functions Name print_stack — Print out stack from string. Synopsis function print_stack(stk:string) Arguments String with list of hexidecimal addresses. Description Perform a symbolic lookup of the addresses in the given string, which is assumed to be the result of a prior call to backtrace.
Name modname — Return the kernel module name loaded at the address. Synopsis function modname:string(addr:long) Arguments addr The address. Description Returns the module name associated with the given address if known. If not known it will return the string “<unknown>”. If the address was not in a kernel module, but in the kernel itself, then the string “kernel”...
Chapter 3. Context Functions function symdata:string(addr:long) Arguments addr The address to translate. Description Returns the (function) symbol name associated with the given address if known, plus the module name (between brackets) and the offset inside the module, plus the size of the symbol function. If any element is not known it will be ommitted and if the symbol name is unknown it will return the hex string for the given address.
Description Returns the (function) symbol name associated with the given address in the current task if known, plus the module name (between brackets) and the offset inside the module (shared library), plus the size of the symbol function. If any element is not known it will be ommitted and if the symbol name is unknown it will return the hex string for the given address.
Chapter 3. Context Functions Synopsis function backtrace:string() Arguments None Description Return a string of hex addresses that are a backtrace of the stack. Output may be truncated as per maximum string length. Name caller — Return name and address of calling function Synopsis function caller:string() Arguments...
Description Return the address of the calling function. Works only for return probes at this time. Name print_ubacktrace — Print stack back trace for current task. EXPERIMENTAL! Synopsis function print_ubacktrace() Arguments None Description Equivalent to print_ustack(ubacktrace), except that deeper stack nesting may be supported. Return nothing.
Chapter 4. Timestamp Functions Each timestamp function returns a value to indicate when a function is executed. These returned values can then be used to indicate when an event occurred, provide an ordering for events, or compute the amount of time elapsed between two time stamps. Name get_cycles —...
Chapter 5. Memory Tapset This family of probe points is used to probe memory-related events. It contains the following probe points: Name vm_fault_contains — Test return value for page fault reason Synopsis function vm_fault_contains:long(value:long,test:long) Arguments value The fault_type returned by vm.page_fault.return test The type of fault to test for (VM_FAULT_OOM or similar) Name...
Chapter 5. Memory Tapset Synopsis vm.pagefault.return Values fault_type Returns either 0 (VM_FAULT_OOM) for out of memory faults, 2 (VM_FAULT_MINOR) for minor faults, 3 (VM_FAULT_MAJOR) for major faults, or 1 (VM_FAULT_SIGBUS) if the fault was neither OOM, minor fault, nor major fault. Name addr_to_node —...
Name vm.write_shared_copy — Page copy for shared page write. Synopsis vm.write_shared_copy Values zero Boolean indicating whether it is a zero page (can do a clear instead of a copy). address The address of the shared write. Context The process attempting the write. Description Fires when a write to a shared page requires a page copy.
Chapter 5. Memory Tapset Synopsis vm.munmap Values length The length of the memory segment address The requested address Context The process calling munmap. Name vm.brk — Fires when a brk is requested (i.e. the heap will be resized). Synopsis vm.brk Values length The length of the memory segment...
Page 37
Values task The task being killed Context The process that tried to consume excessive memory, and thus triggered the OOM.
Chapter 6. IO Scheduler Tapset This family of probe points is used to probe IO scheduler activities. It contains the following probe points: Name ioscheduler.elv_next_request — Fires when a request is retrieved from the request queue Synopsis ioscheduler.elv_next_request Values elevator_name The type of I/O elevator currently enabled Name ioscheduler.elv_next_request.return —...
Chapter 6. IO Scheduler Tapset Synopsis ioscheduler.elv_add_request Values req_flags Request flags Address of the request disk_major Disk major number of the request elevator_name The type of I/O elevator currently enabled disk_minor Disk minor number of the request Name ioscheduler.elv_completed_request — Fires when a request is completed Synopsis ioscheduler.elv_completed_request Values...
Chapter 7. SCSI Tapset This family of probe points is used to probe SCSI activities. It contains the following probe points: Name scsi.ioentry — Prepares a SCSI mid-layer request Synopsis scsi.ioentry Values disk_major The major number of the disk (-1 if no information) device_state The current state of the device.
Chapter 7. SCSI Tapset channel The channel number data_direction The data_direction specifies whether this command is from/to the device. 0 (DMA_BIDIRECTIONAL), 1 (DMA_TO_DEVICE), 2 (DMA_FROM_DEVICE), 3 (DMA_NONE) request_buffer The request buffer address Name scsi.iodone — SCSI command completed by low level driver and enqueued into the done queue. Synopsis scsi.iodone Values...
Page 43
Values The lun number host_no The host number device_state The current state of the device dev_id The scsi device id channel The channel number data_direction The data_direction specifies whether this command is from/to the device goodbytes The bytes completed.
Chapter 8. Networking Tapset This family of probe points is used to probe the activities of the network device and protocol layers. Name netdev.receive — Data recieved from network device. Synopsis netdev.receive Values protocol Protocol of recieved packet. dev_name The name of the device. e.g: eth0, ath1. length The length of the receiving buffer.
Chapter 8. Networking Tapset Name tcp.sendmsg — Sending a tcp message Synopsis tcp.sendmsg Values name Name of this probe size Number of bytes to send sock Network socket Context The process which sends a tcp message Name tcp.sendmsg.return — Sending TCP message is done Synopsis tcp.sendmsg.return Values...
Synopsis tcp.recvmsg Values saddr A string representing the source IP address daddr A string representing the destination IP address name Name of this probe sport TCP source port dport TCP destination port size Number of bytes to be received sock Network socket Context The process which receives a tcp message...
Chapter 8. Networking Tapset sport TCP source port dport TCP destination port size Number of bytes received or error code if an error occurred. Context The process which receives a tcp message Name tcp.disconnect — TCP socket disconnection Synopsis tcp.disconnect Values saddr A string representing the source IP address...
Synopsis tcp.disconnect.return Values Error code (0: no error) name Name of this probe Context The process which disconnects tcp Name tcp.setsockopt — Call to setsockopt Synopsis tcp.setsockopt Values optstr Resolves optname to a human-readable format level The level at which the socket options will be manipulated optlen Used to access values for setsockopt name...
Chapter 8. Networking Tapset Name tcp.setsockopt.return — Return from setsockopt Synopsis tcp.setsockopt.return Values Error code (0: no error) name Name of this probe Context The process which calls setsockopt Name tcp.receive — Called when a TCP packet is received Synopsis tcp.receive Values TCP URG flag...
TCP ACK flag TCP SYN flag TCP FIN flag sport TCP source port Name udp.sendmsg — Fires whenever a process sends a UDP message Synopsis udp.sendmsg Values name The name of this probe size Number of bytes sent by the process sock Network socket used by the process Context...
Chapter 8. Networking Tapset size Number of bytes sent by the process Context The process which sent a UDP message Name udp.recvmsg — Fires whenever a UDP message is received Synopsis udp.recvmsg Values name The name of this probe size Number of bytes received by the process sock Network socket used by the process...
Context The process which received a UDP message Name udp.disconnect — Fires when a process requests for a UDP disconnection Synopsis udp.disconnect Values flags Flags (e.g. FIN, etc) name The name of this probe sock Network socket used by the process Context The process which requests a UDP disconnection Name...
Chapter 8. Networking Tapset Name ip_ntop — returns a string representation from an integer IP number Synopsis function ip_ntop:string(addr:long) Arguments addr the ip represented as an integer...
Chapter 9. Socket Tapset This family of probe points is used to probe socket activities. It contains the following probe points: Name socket.send — Message sent on a socket. Synopsis socket.send Values success Was send successful? (1 = yes, 0 = no) protocol Protocol value flags...
Chapter 9. Socket Tapset socket.receive Values success Was send successful? (1 = yes, 0 = no) protocol Protocol value flags Socket flags value name Name of this probe state Socket state value size Size of message received (in bytes) or error code if success = 0 type Socket type value family...
state Socket state value size Message size in bytes type Socket type value family Protocol family value Context The message sender Description Fires at the beginning of sending a message on a socket via the the sock_sendmsg function Name socket.sendmsg.return — Return from socket.sendmsg. Synopsis socket.sendmsg.return Values...
Chapter 9. Socket Tapset family Protocol family value Context The message sender. Description Fires at the conclusion of sending a message on a socket via the sock_sendmsg function Name socket.recvmsg — Message being received on socket Synopsis socket.recvmsg Values protocol Protocol value flags Socket flags value...
Name socket.recvmsg.return — Return from Message being received on socket Synopsis socket.recvmsg.return Values success Was receive successful? (1 = yes, 0 = no) protocol Protocol value flags Socket flags value name Name of this probe state Socket state value size Size of message received (in bytes) or error code if success = 0 type Socket type value...
Chapter 9. Socket Tapset socket.aio_write Values protocol Protocol value flags Socket flags value name Name of this probe state Socket state value size Message size in bytes type Socket type value family Protocol family value Context The message sender Description Fires at the beginning of sending a message on a socket via the sock_aio_write function Name socket.aio_write.return —...
flags Socket flags value name Name of this probe state Socket state value size Size of message received (in bytes) or error code if success = 0 type Socket type value family Protocol family value Context The message receiver. Description Fires at the conclusion of sending a message on a socket via the sock_aio_write function Name socket.aio_read —...
Chapter 9. Socket Tapset type Socket type value family Protocol family value Context The message sender Description Fires at the beginning of receiving a message on a socket via the sock_aio_read function Name socket.aio_read.return — Conclusion of message received via sock_aio_read Synopsis socket.aio_read.return Values...
Description Fires at the conclusion of receiving a message on a socket via the sock_aio_read function Name socket.writev — Message sent via socket_writev Synopsis socket.writev Values protocol Protocol value flags Socket flags value name Name of this probe state Socket state value size Message size in bytes type...
Chapter 9. Socket Tapset socket.writev.return Values success Was send successful? (1 = yes, 0 = no) protocol Protocol value flags Socket flags value name Name of this probe state Socket state value size Size of message sent (in bytes) or error code if success = 0 type Socket type value family...
flags Socket flags value name Name of this probe state Socket state value size Message size in bytes type Socket type value family Protocol family value Context The message sender Description Fires at the beginning of receiving a message on a socket via the sock_readv function Name socket.readv.return —...
Chapter 9. Socket Tapset size Size of message received (in bytes) or error code if success = 0 type Socket type value family Protocol family value Context The message receiver. Description Fires at the conclusion of receiving a message on a socket via the sock_readv function Name socket.create —...
Name socket.create.return — Return from Creation of a socket Synopsis socket.create.return Values success Was socket creation successful? (1 = yes, 0 = no) protocol Protocol value Error code if success == 0 name Name of this probe requester Requested by user process or the kernel (1 = kernel, 0 = user) type Socket type value family...
Chapter 9. Socket Tapset Values protocol Protocol value flags Socket flags value name Name of this probe state Socket state value type Socket type value family Protocol family value Context The requester (user process or kernel) Description Fires at the beginning of closing a socket. Name socket.close.return —...
Name sock_prot_num2str — Given a protocol number, return a string representation. Synopsis function sock_prot_num2str:string(proto:long) Arguments proto The protocol number. Name sock_prot_str2num — Given a protocol name (string), return the corresponding protocol number. Synopsis function sock_prot_str2num:long(proto:string) Arguments proto The protocol name. Name sock_fam_num2str —...
Chapter 9. Socket Tapset Synopsis function sock_fam_str2num:long(family:string) Arguments family The family name. Description protocol family number. Name sock_state_num2str — Given a socket state number, return a string representation. Synopsis function sock_state_num2str:string(state:long) Arguments state The state number. Name sock_state_str2num — Given a socket state string, return the corresponding state number. Synopsis function sock_state_str2num:long(state:string) Arguments...
Chapter 10. Kernel Process Tapset This family of probe points is used to probe process-related activities. It contains the following probe points: Name kprocess.create — Fires whenever a new process is successfully created Synopsis kprocess.create Values new_pid The PID of the newly created process Context Parent of the created process.
Chapter 10. Kernel Process Tapset Name kprocess.exec — Attempt to exec to a new program Synopsis kprocess.exec Values filename The path to the new executable Context The caller of exec. Description Fires whenever a process attempts to exec to a new program. Name kprocess.exec_complete —...
Synopsis kprocess.exit Values code The exit code of the process Context The process which is terminating. Description Fires when a process terminates. This will always be followed by a kprocess.release, though the latter may be delayed if the process waits in a zombie state. Name kprocess.release —...
Page 75
Chapter 11. Signal Tapset This family of probe points is used to probe signal activities. It contains the following probe points: Name signal.send — Signal being sent to a process Synopsis signal.send Values send2queue Indicates whether the signal is sent to an existing sigqueue name The name of the function used to send out the signal task...
Chapter 11. Signal Tapset Name signal.send.return — Signal being sent to a process completed Synopsis signal.send.return Values retstr The return value to either __group_send_sig_info, specific_send_sig_info, or send_sigqueue send2queue Indicates whether the sent signal was sent to an existing sigqueue name The name of the function used to send out the signal shared Indicates whether the sent signal is shared by the thread group.
Synopsis signal.checkperm Values name Name of the probe point; default value is signal.checkperm task A task handle to the signal recipient sinfo The address of the siginfo structure si_code Indicates the signal type sig_name A string representation of the signal The number of the signal pid_name Name of the process receiving the signal...
Chapter 11. Signal Tapset Synopsis signal.wakeup Values resume Indicates whether to wake up a task in a STOPPED or TRACED state state_mask A string representation indicating the mask of task states to wake. Possible values are TASK_INTERRUPTIBLE, TASK_STOPPED, TASK_TRACED, and TASK_INTERRUPTIBLE. pid_name Name of the process to wake sig_pid...
Synopsis signal.check_ignored.return Values retstr Return value as a string name Name of the probe point; default value is signal.checkperm Name signal.force_segv — Forcing send of SIGSEGV Synopsis signal.force_segv Values sig_name A string representation of the signal The number of the signal pid_name Name of the process receiving the signal sig_pid...
Chapter 11. Signal Tapset name Name of the probe point; default value is force_sigsegv Name signal.syskill — Sending kill signal to a process Synopsis signal.syskill Values The specific signal sent to the process The PID of the process receiving the signal Name signal.syskill.return —...
The specific signal sent to the process The PID of the process receiving the kill signal Description The tkill call is analogous to kill(2), except that it also allows a process within a specific thread group to be targetted. Such processes are targetted through their unique thread IDs (TID). Name signal.systkill.return —...
Chapter 11. Signal Tapset Description The tgkill call is similar to tkill, except that it also allows the caller to specify the thread group ID of the thread to be signalled. This protects against TID reuse. Name signal.sys_tgkill.return — Sending kill signal to a thread group completed Synopsis signal.sys_tgkill.return Values...
Synopsis signal.send_sig_queue.return Values retstr Return value as a string Name signal.pending — Examining pending signal Synopsis signal.pending Values sigset_size The size of the user-space signal set sigset_add The address of the user-space signal set (sigset_t) Description This probe is used to examine a set of signals pending for delivery to a specific thread. This normally occurs when the do_sigpending kernel function is executed.
Chapter 11. Signal Tapset Name signal.handle — Signal handler being invoked Synopsis signal.handle Values regs The address of the kernel-mode stack area sig_code The si_code value of the siginfo signal sig_mode Indicates whether the signal was a user-mode or kernel-mode signal sinfo The address of the siginfo table oldset_addr...
Synopsis signal.do_action Values sa_mask The new mask of the signal oldsigact_addr The address of the old sigaction struct associated with the signal The signal to be examined/changed sa_handler The new handler of the signal sigact_addr The address of the new sigaction struct associated with the signal Name signal.do_action.return —...
Chapter 11. Signal Tapset Values Indicates how to change the blocked signals; possible values are SIG_BLOCK=0 (for blocking signals), SIG_UNBLOCK=1 (for unblocking signals), and SIG_SETMASK=2 for setting the signal mask. oldsigset_addr The old address of the signal set (sigset_t) sigset The actual value to be set for sigset_t sigset_addr The address of the signal set (sigset_t) to be implemented...
Need help?
Do you have a question about the ENTERPRISE LINUX 5.4 - SYSTEMTAP TAPSET and is the answer not in the manual?
Questions and answers