JFIF$        dd7 

Viewing File: /usr/share/doc/systemtap-sdt-devel/README

systemtap: a linux trace/probe tool

Visit the project web site at <http://sourceware.org/systemtap>,
for documentation and mailing lists for developers and users.

This is free software.
See the COPYING file for redistribution/modification terms.
See the INSTALL file for generic build instructions.
See the HACKING file for contribution advice.

Prerequisites:

- linux kernel
- kernel module build environment (kernel-devel rpm) and/or dyninst
- optionally, debugging information for kernel/user-space being instrumented
- C compiler (same as what kernel was compiled with), to build kernel modules
- C++11 compiler such as gcc 4.8+, to build systemtap itself
- elfutils 0.151+ with libdwfl for debugging information parsing
- Python for tools which are scripts, such as dtrace(1)
- root privileges

Installation steps:

- If equipped with elfutils version 0.178 or later, try using debuginfod
  for automatic debuginfo downloading.  This experimental public server
  may be enough:
  % export DEBUGINFOD_URLS=https://debuginfod.elfutils.org/
  % export DEBUGINFOD_PROGRESS=1
  See https://sourceware.org/elfutils/Debuginfod.html for more details.
  
- Otherwise, install any debuginfo packages you need, for kernel
  and/or userspace.  On modern Fedora, # debuginfo-install kernel [...]
  
  (Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc.
  variants.  Each likely has a corresponding development and debuginfo
  package.)

- Install the systemtap package.
  On modern Fedora, # yum install systemtap systemtap-runtime

Build steps:

- Consider installing the kernel-debuginfo, kernel-devel, gcc and
  dependent packages (or see below if you are building your own
  kernels from source).  If using only the pure-userspace dyninst
  backend, install gcc and dyninst-devel.
  
- If available, install your distribution's copy of elfutils and its
  development headers/libraries.
  Or if desired, build elfutils separately one time, and install
  it to /usr/local.
  See https://elfutils.org/
  elfutils version 0.178 introduces automatic debuginfo downloading,
  which can makes systemtap usage easier.

- On modern Fedora, install general optional build-requisites:
  # yum-builddep systemtap
  On modern Debian/Ubuntu, similarly:
  # apt-get build-dep systemtap

- Download systemtap sources:
  https://sourceware.org/systemtap/ftp/releases/
  https://sourceware.org/systemtap/ftp/snapshots/
  (or)
  git clone git://sourceware.org/git/systemtap.git
      (or) https://sourceware.org/git/systemtap.git

- Build systemtap normally:
  % .../configure [other autoconf options]
  Add env LDFLAGS=-L/path/ CPPFLAGS=-I/path/ before configure
  to locate libraries in non-system directories.

  Consider configuring with "--prefix=DIRECTORY" to specify an
  installation directory other than /usr/local.  It can be an ordinary
  personal directory.

  % make all
  # make install
  To uninstall systemtap:
  # make uninstall

  Alternately, on a Fedora-like system:
  % make rpm
  # rpm -i /path/to/rpmbuild/.../systemtap*rpm


- Run systemtap:

  To run systemtap after installation, add $prefix/bin to your $PATH, or
  refer to $prefix/bin/stap directly.  If you keep your build tree
  around, you can also use the "stap" binary there.  

  Some samples should be available under $prefix/share/doc/systemtap/examples.

  For the normal linux-kernel-module based backend, run "stap" as
  root.  If desired, create "stapdev" and "stapusr" entries in
  /etc/groups.  Any users in "stapdev"+"stapusr" will be able to run
  systemtap as if with root privileges.  Users in "stapusr" only may
  launch (with "staprun") pre-compiled probe modules (created by "stap
  -p4 ...") that a system administrator copied under
  /lib/modules/`uname -r`/systemtap.  "stapusr" may also be permitted
  to create arbitrary unprivileged systemtap scripts of their own.
  See README.unprivileged for additional setup instructions.

  To run a simple test.
  # stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'

  To run the full test suite from the build tree, install dejagnu,
  then run with root privileges:
  # make installcheck

  For the prototype dyninst pure-userspace backend, run "stap" as any user.
  % stap --runtime=dyninst -e 'probe process.function("*") { 
                               println(pn(), ":", $$parms) }' -c 'ls'

  For the prototype bpf backend, run "stap" as "root"
  # stap --runtime=bpf -e 'probe kernel.function("do_exit") {
                                 printf("bye %d\n", pid()) }'



Tips:

- By default, systemtap looks for the debug info in these locations:
  /boot/vmlinux-`uname -r`
  /usr/lib/debug/lib/modules/`uname -r`/vmlinux
  /lib/modules/`uname -r`/vmlinux
  /lib/modules/`uname -r`/build/vmlinux


Building a kernel.org kernel:

- Build the kernel using your normal procedures.  Enable
  CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS,
  CONFIG_MODULES, CONFIG_MODULE_UNLOAD, CONFIG_UPROBES if able
- % make modules_install install headers_install
- Boot into the kernel.

- If you wish to leave the kernel build tree in place, simply run
  % stap -r /path/to/kernel/build/tree [...]
  You're done.

- Or else, if you wish to install the kernel build/debuginfo data into
  a place where systemtap will find it without the "-r" option:
  % ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build 

- Instead of using the "-r" option, you can also use the environment 
  variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data.
Back to Directory  nL+D550H?Mx ,D"v]qv;6*Zqn)ZP0!1 A "#a$2Qr D8 a Ri[f\mIykIw0cuFcRı?lO7к_f˓[C$殷WF<_W ԣsKcëIzyQy/_LKℂ;C",pFA:/]=H  ~,ls/9ć:[=/#f;)x{ٛEQ )~ =𘙲r*2~ a _V=' kumFD}KYYC)({ *g&f`툪ry`=^cJ.I](*`wq1dđ#̩͑0;H]u搂@:~וKL Nsh}OIR*8:2 !lDJVo(3=M(zȰ+i*NAr6KnSl)!JJӁ* %݉?|D}d5:eP0R;{$X'xF@.ÊB {,WJuQɲRI;9QE琯62fT.DUJ;*cP A\ILNj!J۱+O\͔]ޒS߼Jȧc%ANolՎprULZԛerE2=XDXgVQeӓk yP7U*omQIs,K`)6\G3t?pgjrmۛجwluGtfh9uyP0D;Uڽ"OXlif$)&|ML0Zrm1[HXPlPR0'G=i2N+0e2]]9VTPO׮7h(F*癈'=QVZDF,d߬~TX G[`le69CR(!S2!P <0x<!1AQ "Raq02Br#SCTb ?Ζ"]mH5WR7k.ۛ!}Q~+yԏz|@T20S~Kek *zFf^2X*(@8r?CIuI|֓>^ExLgNUY+{.RѪ τV׸YTD I62'8Y27'\TP.6d&˦@Vqi|8-OΕ]ʔ U=TL8=;6c| !qfF3aů&~$l}'NWUs$Uk^SV:U# 6w++s&r+nڐ{@29 gL u"TÙM=6(^"7r}=6YݾlCuhquympǦ GjhsǜNlɻ}o7#S6aw4!OSrD57%|?x>L |/nD6?/8w#[)L7+6〼T ATg!%5MmZ/c-{1_Je"|^$'O&ޱմTrb$w)R$& N1EtdU3Uȉ1pM"N*(DNyd96.(jQ)X 5cQɎMyW?Q*!R>6=7)Xj5`J]e8%t!+'!1Q5 !1 AQaqё#2"0BRb?Gt^## .llQT $v,,m㵜5ubV =sY+@d{N! dnO<.-B;_wJt6;QJd.Qc%p{ 1,sNDdFHI0ГoXшe黅XۢF:)[FGXƹ/w_cMeD,ʡcc.WDtA$j@:) -# u c1<@ۗ9F)KJ-hpP]_x[qBlbpʖw q"LFGdƶ*s+ډ_Zc"?%t[IP 6J]#=ɺVvvCGsGh1 >)6|ey?Lӣm,4GWUi`]uJVoVDG< SB6ϏQ@ TiUlyOU0kfV~~}SZ@*WUUi##; s/[=!7}"WN]'(L! ~y5g9T̅JkbM' +s:S +B)v@Mj e Cf jE 0Y\QnzG1д~Wo{T9?`Rmyhsy3!HAD]mc1~2LSu7xT;j$`}4->L#vzŏILS ֭T{rjGKC;bpU=-`BsK.SFw4Mq]ZdHS0)tLg