From 518f6dfdd0c449edc142706a70898dd37f595cf3 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Wed, 22 Oct 2008 14:22:44 +1000 Subject: more edits as per wcohen --- .../en-US/CrossInstrumenting.xml | 4 +- .../en-US/Installation.xml | 15 +------ doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 39 +++++++++++++----- .../en-US/SystemTap_Beginners_Guide.xml | 2 +- .../en-US/Useful_Scripts-nettop.xml | 48 +++++++++++----------- .../en-US/Using_SystemTap.xml | 27 ++++++++++++ 6 files changed, 85 insertions(+), 50 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide/en-US') diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml index f428f5e5..b0d712bd 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml @@ -128,9 +128,9 @@ enabled=1 staprun instrumentation - For example, to create the instrumentation module simple.ko from the SystemTap script (from ) for the target kernel 2.6.25.9-76.fc9 (on i686 architecture), use the following command: + For example, to create the instrumentation module simple.ko from a SystemTap script named simple.stp for the target kernel 2.6.25.9-76.fc9 (on i686 architecture), use the following command: - + stap -r 2.6.25.9-76.fc9.x86_64 simple.stp -m module This will create a module named simple.ko. To use the instrumentation module simple.ko, copy it to the target system and run the following command (on the target system): diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml index f9c9a819..1bde952e 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml @@ -136,18 +136,7 @@ As mentioned earlier in , kernel-debuginf If you are currently using the kernel you wish to probe with SystemTap, you can immediately test whether the deployment was successful. If not, you will need to reboot and load the appropriate kernel. -To start the test, create the following SystemTap script (ensure that you are using the filename extension .stp): - - - simple.stp - - -probe kernel.function("vfs_read") {exit()} - - - - - is a SystemTap script that simply exits the first time it detects a virtual file system read. If the SystemTap deployment was successful, you should get the following verbose output: +To start the test, run the command stap -v -e 'probe vfs.read {exit()}. This command simply instructs SystemTap to exit properly once a virtual file system read is detected. If the SystemTap deployment was successful, you should get the following verbose output: Pass 1: parsed user script and 55 library script(s) in 340usr/10sys/380real ms. @@ -159,7 +148,7 @@ Pass 5: run completed in 40usr/210sys/260real ms. - The last two lines of the output (i.e. beginning with Pass 5 indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, detect the event being probed (in the case of , a virtual file system read), and close it with no errors. + The last two lines of the output (i.e. beginning with Pass 5 indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, detect the event being probed (in this case, a virtual file system read), and close it with no errors. diff --git a/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml b/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml index b69e00df..1a55010b 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml @@ -13,7 +13,7 @@ - + diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml index b1d3f846..331f49a6 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml @@ -30,7 +30,7 @@ probe netdev.transmit execname[p] = execname() user[p] = uid() ifdevs[p, dev_name] = dev_name - ifxmit[p, dev_name] <<< length + ifxmit[p, dev_name] <<< length ifpid[p, dev_name] ++ } @@ -40,7 +40,7 @@ probe netdev.receive execname[p] = execname() user[p] = uid() ifdevs[p, dev_name] = dev_name - ifrecv[p, dev_name] <<< length + ifrecv[p, dev_name] <<< length ifpid[p, dev_name] ++ } @@ -100,28 +100,28 @@ probe timer.ms(5000) <xref linkend="nettop"/> Sample Output [...] - PID UID DEV XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND - 0 0 eth0 0 5 0 0 swapper -11178 0 eth0 2 0 0 0 synergyc - - PID UID DEV XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND - 2886 4 eth0 79 0 5 0 cups-polld -11362 0 eth0 0 61 0 5 firefox - 0 0 eth0 3 32 0 3 swapper - 2886 4 lo 4 4 0 0 cups-polld -11178 0 eth0 3 0 0 0 synergyc - - PID UID DEV XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND - 0 0 eth0 0 6 0 0 swapper - 2886 4 lo 2 2 0 0 cups-polld -11178 0 eth0 3 0 0 0 synergyc - 3611 0 eth0 0 1 0 0 Xorg - - PID UID DEV XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND - 0 0 eth0 3 42 0 2 swapper -11178 0 eth0 43 1 3 0 synergyc -11362 0 eth0 0 7 0 0 firefox - 3897 0 eth0 0 1 0 0 multiload-apple + PID UID DEV XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND + 0 0 eth0 0 5 0 0 swapper +11178 0 eth0 2 0 0 0 synergyc + + PID UID DEV XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND + 2886 4 eth0 79 0 5 0 cups-polld +11362 0 eth0 0 61 0 5 firefox + 0 0 eth0 3 32 0 3 swapper + 2886 4 lo 4 4 0 0 cups-polld +11178 0 eth0 3 0 0 0 synergyc + + PID UID DEV XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND + 0 0 eth0 0 6 0 0 swapper + 2886 4 lo 2 2 0 0 cups-polld +11178 0 eth0 3 0 0 0 synergyc + 3611 0 eth0 0 1 0 0 Xorg + + PID UID DEV XMIT_PK RECV_PK XMIT_KB RECV_KB COMMAND + 0 0 eth0 3 42 0 2 swapper +11178 0 eth0 43 1 3 0 synergyc +11362 0 eth0 0 7 0 0 firefox + 3897 0 eth0 0 1 0 0 multiload-apple [...] diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml index 43105edf..447f3d62 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml @@ -117,6 +117,33 @@ 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. + + stapdev and stapusr + Running stap and staprun requires elevated privileges to the system. However, not all users can be granted root access just to run SystemTap. In some cases, for instance, you may want to allow a non-privileged user to run SystemTap instrumentation on his machine. + + +To allow ordinary users to run SystemTap without root access, add them to one of these user groups: + + + + + stapdev + + + Members of this group can use stap to run SystemTap scripts, or staprun to run SystemTap instrumentation modules. + + + + + + stapusr + + + Members of this group can only run staprun to run SystemTap instrumentation modules. In addition, they can only run those modules from /lib/modules/kernel_version/systemtap/. Note that this directory must be owned only by the root user, and must only be writable by the root user. + + + + -- cgit