From 8a1d8fbf543260108adf064fe368399dc477567e Mon Sep 17 00:00:00 2001 From: William Cohen Date: Tue, 30 Mar 2010 12:01:18 -0400 Subject: Add documentation about Flight Recorder Mode to Beginner's Guide --- .../en-US/Using_SystemTap.xml | 136 +++++++++++++++++++++ 1 file changed, 136 insertions(+) diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml index acaf0e17..ce855c9d 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml @@ -166,6 +166,17 @@ + + -S size,count + + Limit files to size megabytes and + limit the the number of files kept around to + count. The file names will have a + sequence number suffix. This option implements logrotate operations + for SystemTap. + + + -x process ID @@ -194,6 +205,15 @@ string rather than a file as input for systemtap translator. + + + -F + + Use SystemTap's Flight recorder mode and make the script a + background process. For more information about flight + recorder mode, refer to . + + You can also instruct stap to run scripts from standard input using the switch -. To illustrate: @@ -231,6 +251,122 @@ echo "probe timer.s(1) {exit()}" | stap - The stap options -v and -o also work for staprun. For more information about staprun, refer to man staprun. +
+SystemTap Flight Recorder Mode + +flight recorder mode + + + +SystemTap's flight recorder mode allows you to run a SystemTap script +run for long periods and just focus on recent output. The flight +recorder mode (the -F option) limits the amount of output +generated. There are two variations of the flight recorder mode: +in-memory and file mode. In both cases the SystemTap script runs as a +background process. + + +
+In-memory Flight Recorder + +flight recorder mode +in-memory mode + + + +When flight recorder mode (the -F option) is used without a +file name SystemTap uses a buffer in kernel memory to store the output of the +script. The SystemTap instrumentation module will load and the probes start +running, the instrumentation will then detach and be put in the background. When +the interesting event occurs, you can reattach to the instrumentation and see +the recent output in the memory buffer and any continuing output. The following +command starts a script using the flight recorder in-memory mode: + + + +stap -F iotime.stp + + + +Once the script starts, you will see a message like the following that +provides the command to reconnect to the running script: + + + +Disconnecting from systemtap module. +To reconnect, type "staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556" + + + +When the interesting event occurs, you reattach to the currently running script +and output the recent data in the memory buffer and get continuing output with +the following command: + + + +staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556 + + + +By default the kernel buffer is 1MB in size and it can be increased with the +-s option specifying the size in megabytes (rounded up to the +next power over 2) for the buffer. For example -s2 on the +SystemTap command line would specify 2MB for the buffer. + +
+ +
+File Flight Recorder + +flight recorder mode +file mode + + + +The flight recorder mode can also store data to files. The number and size of +the files kept is controlled by the -S option followed by two +numerical arguments separated by a comma. The first argument is the maximum size +in megabytes for the each output file. The second argument is the number of +recent files to keep. The file name is specified by the -o +option followed by the name. SystemTap will add a number suffix to the file name +to indicate the order of the files. The following will start SystemTap in file +flight recorder mode with the output going to files named +/tmp/iotime.log.[0-9]+ and each +file 1MB or smaller and keeping latest two files: + + + +stap -F -o /tmp/pfaults.log -S 1,2 pfaults.stp + + + +The number printed by the command is the process ID. Sending a SIGTERM to +the process will shutdown the SystemTap script and stop the data collection. For +example if the previous command listed the 7590 as the process ID, the following +command whould shutdown the systemtap script: + + + +kill -s SIGTERM 7590 + + + +Only the most recent two file generated by the script are kept and the older +files are been removed. Thus, ls -sh /tmp/pfaults.log.* +shows the only two files: + + + +1020K /tmp/pfaults.log.5 44K /tmp/pfaults.log.6 + + + +One can look at the highest number file for the latest data, in this case +/tmp/pfaults.log.6. + + +
+
-- cgit