drivers/staging/ktap/README.md

   1 # ktap
   2
   3 A New Scripting Dynamic Tracing Tool For Linux
   4 [www.ktap.org][homepage]
   5
   6 ktap is a new scripting dynamic tracing tool for Linux,
   7 it uses a scripting language and lets users trace the Linux kernel dynamically.
   8 ktap is designed to give operational insights with interoperability
   9 that allows users to tune, troubleshoot and extend kernel and application.
  10 It's similar with Linux Systemtap and Solaris Dtrace.
  11
  12 ktap have different design principles from Linux mainstream dynamic tracing
  13 language in that it's based on bytecode, so it doesn't depend upon GCC,
  14 doesn't require compiling kernel module for each script, safe to use in
  15 production environment, fulfilling the embedded ecosystem's tracing needs.
  16
  17 More information can be found at [ktap homepage][homepage].
  18
  19 [homepage]: http://www.ktap.org
  20
  21 ## Highlights
  22
  23   * simple but powerful scripting language
  24   * register based interpreter (heavily optimized) in Linux kernel
  25   * small and lightweight (6KLOC of interpreter)
  26   * not depend on gcc for each script running
  27   * easy to use in embedded environment without debugging info
  28   * support for tracepoint, kprobe, uprobe, function trace, timer, and more
  29   * supported in x86, arm, ppc, mips
  30   * safety in sandbox
  31
  32 ## Building & Running
  33
  34 1. Clone ktap from github
  35
  36         $ git clone http://github.com/ktap/ktap.git
  37
  38 2. Compiling ktap
  39
  40         $ cd ktap
  41         $ make       #generate ktapvm kernel module and ktap binary
  42
  43 3. Load ktapvm kernel module(make sure debugfs mounted)
  44
  45         $ make load  #need to be root or have sudo access
  46
  47 4. Running ktap
  48
  49         $ ./ktap samples/helloworld.kp
  50
  51
  52 ## Examples
  53
  54 1. simplest one-liner command to enable all tracepoints
  55
  56         ktap -e "trace *:* { print(argevent) }"
  57
  58 2. syscall tracing on target process
  59
  60         ktap -e "trace syscalls:* { print(argevent) }" -- ls
  61
  62 3. ftrace(kernel newer than 3.3, and must compiled with CONFIG_FUNCTION_TRACER)
  63
  64         ktap -e "trace ftrace:function { print(argevent) }"
  65
  66         ktap -e "trace ftrace:function /ip==mutex*/ { print(argevent) }"
  67
  68 4. simple syscall tracing
  69
  70         trace syscalls:* {
  71                 print(cpu(), pid(), execname(), argevent)
  72         }
  73
  74 5. syscall tracing in histogram style
  75
  76         s = {}
  77
  78         trace syscalls:sys_enter_* {
  79                 s[argname] += 1
  80         }
  81
  82         trace_end {
  83                 histogram(s)
  84         }
  85
  86 6. kprobe tracing
  87
  88         trace probe:do_sys_open dfd=%di fname=%dx flags=%cx mode=+4($stack) {
  89                 print("entry:", execname(), argevent)
  90         }
  91
  92         trace probe:do_sys_open%return fd=$retval {
  93                 print("exit:", execname(), argevent)
  94         }
  95
  96 7. uprobe tracing
  97
  98         trace probe:/lib/libc.so.6:malloc {
  99                 print("entry:", execname(), argevent)
 100         }
 101
 102         trace probe:/lib/libc.so.6:malloc%return {
 103                 print("exit:", execname(), argevent)
 104         }
 105
 106 8. stapsdt tracing (userspace static marker)
 107
 108         trace sdt:/lib64/libc.so.6:lll_futex_wake {
 109                 print("lll_futex_wake", execname(), argevent)
 110         }
 111
 112         or:
 113
 114         #trace all static mark in libc
 115         trace sdt:/lib64/libc.so.6:* {
 116                 print(execname(), argevent)
 117         }
 118
 119 9. timer
 120
 121         tick-1ms {
 122                 printf("time fired on one cpu\n");
 123         }
 124
 125         profile-2s {
 126                 printf("time fired on every cpu\n");
 127         }
 128
 129 10. FFI (Call kernel function from ktap script, need compile with FFI=1)
 130
 131         cdef[[
 132                 int printk(char *fmt, ...);
 133         ]]
 134
 135         C.printk("This message is called from ktap ffi\n")
 136
 137 More examples can be found at [samples][samples_dir] directory.
 138
 139 [samples_dir]: https://github.com/ktap/ktap/tree/master/samples
 140
 141 ## Mailing list
 142
 143 ktap@freelists.org
 144 You can subscribe to ktap mailing list at link (subscribe before posting):
 145 http://www.freelists.org/list/ktap
 146
 147
 148 ## Copyright and License
 149
 150 ktap is licensed under GPL v2
 151
 152 Copyright (C) 2012-2013, Jovi Zhangwei <jovi.zhangwei@gmail.com>.
 153 All rights reserved.
 154
 155
 156 ## Contribution
 157
 158 ktap is still under active development, so contributions are welcome.
 159 You are encouraged to report bugs, provide feedback, send feature request,
 160 or hack on it.
 161
 162
 163 ## See More
 164
 165 More info can be found at [documentation][tutorial]
 166 [tutorial]: http://www.ktap.org/doc/tutorial.html
 167