From f32ca759d95515be3c7728c9ffd7afcfa49e1ce0 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Wed, 15 Oct 2008 15:05:02 +1000 Subject: tried improving Installation, also trying out new chapter on advanced scripts (tentative) --- doc/SystemTap_Beginners_Guide/en-US/Appendix.xml | 10 ++- .../en-US/CrossInstrumenting.xml | 8 +- .../en-US/Installation.xml | 86 +++++++++++++++++++++- .../en-US/Introduction.xml | 50 ++++++++++--- .../en-US/SystemTap_Beginners_Guide.xml | 2 +- .../en-US/Useful_Advanced_Scripts.xml | 30 ++++++++ .../en-US/Useful_Scripts-nettop.xml | 2 +- 7 files changed, 164 insertions(+), 24 deletions(-) create mode 100644 doc/SystemTap_Beginners_Guide/en-US/Useful_Advanced_Scripts.xml (limited to 'doc/SystemTap_Beginners_Guide/en-US') diff --git a/doc/SystemTap_Beginners_Guide/en-US/Appendix.xml b/doc/SystemTap_Beginners_Guide/en-US/Appendix.xml index f7f8ea1d..dbeb3c08 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Appendix.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Appendix.xml @@ -2,12 +2,14 @@ - - + + + Full Version of Advanced Scripts + This appendix contains the full versions of all scripts discussed in . + diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml index cc451ec4..f428f5e5 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml @@ -128,14 +128,14 @@ enabled=1 staprun instrumentation - For example, to create the instrumentation module module.ko from the SystemTap script script.stp 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 the SystemTap script (from ) 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 script.stp -m module +stap -r 2.6.25.9-76.fc9.x86_64 simple.stp -m module -This will create a module named module.ko. To use the instrumentation module module.ko, copy it to the target system and run the following command (on the target system): +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): -staprun module.ko +staprun simple.ko - Most -debuginfo packages for Red Hat Enterprise Linux 5 can be found at the following link (under arch/Debuginfo, where arch is the appropriate architecture for your system: + Most -debuginfo packages for Red Hat Enterprise Linux 5 can be found at the following link (under arch/Debuginfo, where arch is the appropriate architecture for your system: ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/ @@ -57,7 +67,25 @@ uname -r systemtap-runtime - This will install the SystemTap suite of tools. + To do so, run yum install systemtap systemtap-runtime; this will work if your yum repository is configured accordingly. To configure yum, simply add the following file to /etc/yum.repos.d: + + + packages.repo + + +[packages] +name=Packages for OS +baseurl=repository +enabled=1 +gpgcheck=0 + + + + + + In , repository is the full URL of the repository containing the packages you wish to install. The name= parameter, along with the title ([packages]) and filename, can be set arbitrarily, as long as you use the .repo filename extension. + +
- Goals - SystemTap provides the infrastructure to monitor the running Linux kernel for detailed analysis. This can assist in identifying the underlying cause of a performance or functional problem. + Documentation Goals + SystemTap provides the infrastructure to monitor the running Linux kernel for detailed analysis. This can assist administrators and developers in identifying the underlying cause of a performance or functional problem. - Without SystemTap, monitoring the activity of a running kernel would require a tedious instrument, recompile, install, and reboot sequence. SystemTap is designed to eliminate this, allowing users to gather the same information by simply running its suite of tools against specific tapsets or SystemTap scripts. + Without SystemTap, monitoring the activity of a running kernel would require a tedious instrument, recompile, install, and reboot sequence. SystemTap is designed to eliminate this, allowing users to gather the same information by simply running user-written SystemTap scripts. - However, SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. As such, much of the existing documentation for SystemTap is primarily for advanced users. This could present a steep learning curve for administrators or developers whose knowledge of the Linux kernel is little to none. + However, SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. As such, much of the existing documentation for SystemTap is primarily for advanced users. This could present a steep learning curve for administrators or developers with limited knowledge of and experience with the Linux kernel. In line with that, the main goals of the SystemTap Beginner's Guide are as follows: To introduce users to SystemTap, familiarize them with its architecture, and provide setup instructions for all kernel types. - To provide pre-written SystemTap scripts for monitoring detailed activity in different components of the system, along with instructions on how to analyze their output. + To provide pre-written SystemTap scripts for monitoring detailed activity in different components of the system, along with instructions on how to run them and analyze their output. above, Short description on the underlying goals of SystemTap_Beginners_Guide, what we want to teach users. @@ -45,20 +46,47 @@
-->
- SystemTap Versus Other Monitoring Tools + + SystemTap Capabilities ** Short summary; when is SystemTap suitable vs other popular monitoring tools (e.g. top, Oprofile, /proc) + SystemTap was originally developed as a working Linux version of Dtrace. Dtrace is a Sun Microsystems "dynamic tracing" framework that assists administrators in monitoring and troubleshooting kernel and user-space applications in real time. + + SystemTap aims to supplement the existing suite of Linux monitoring tools by providing users with the infrastructure to track kernel activity. In addition, SystemTap combines this capability with two things: + + + Flexibility: SystemTap's framework allows users to develop simple scripts for investigating and monitoring a wide variety of kernel functions, system calls, and other events that occur in kernel-space. With this, SystemTap is not soo much a tool as it is a system that allows you to develop your own kernel-specific forensic and monitoring tools. + + Ease-Of-Use: as mentioned earlier, SystemTap allows users to probe kernel-space events without having to resort to instrument, recompile, install, and reboot the kernel. + + +Most of the SystemTap scripts enumerated in demonstrate system forensics and monitoring capabilities not natively available with other similar tools (such as top, oprofile, or ps). These scripts are provided to give readers extensive examples of the application of SystemTap, which in turn will educate them further on the capabilities they can employ when writing their own SystemTap scripts. + + + + Limitations - TBD - + The current iteration of SystemTap allows for a multitude of options when probing kernel-space events. However, SystemTap's ability to probe user-space events is quite limited. At present, the developmental efforts of the SystemTap community are geared towards improving SystemTap's user-space probing capabilities. + + +
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 ccc97915..b69e00df 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/SystemTap_Beginners_Guide.xml @@ -10,6 +10,7 @@ + @@ -18,7 +19,6 @@ --> - diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Advanced_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Advanced_Scripts.xml new file mode 100644 index 00000000..71aaad9b --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Advanced_Scripts.xml @@ -0,0 +1,30 @@ + + + + + Useful SystemTap Scripts + + This chapter contains several advanced applications of SystemTap. The scripts enumerated herein combine SystemTap scripts with other tools in order to address some complex administrative tasks. All of these scripts are available at the following link: + + http://sourceware.org/systemtap/wiki/WarStories?action=fullsearch&context=180&value=traceio2&titlesearch=Titles + + Due to the relative length of the scripts discussed in this chapter, the full version of each script is documented in . + + this chapter will feature the following scripts: + + http://sourceware.org/systemtap/wiki/WSPSTimeouts?highlight=((WarStories)) + + http://sourceware.org/systemtap/wiki/WSPfiles?highlight=((WarStories)) + + http://sourceware.org/systemtap/wiki/WSPSTimeouts?highlight=%28%28WarStories%29%29 + + WAIT http://sourceware.org/systemtap/wiki/WSPanicOnOom?highlight=((WarStories)) + + http://sourceware.org/systemtap/wiki/WSPfiles?highlight=((WarStories)) + + + + + + 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 d56cbfc1..b1d3f846 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-nettop.xml @@ -4,7 +4,7 @@
- Kernel Profiling + Network Profiling -- cgit