ltt-usertrace/README

   1
   2 LTTng usertrace package
   3
   4 Mathieu Desnoyers <mathieu.desnoyers@polymtl.ca>
   5 March 2006
   6
   7 This package contains all the user space headers and c files necessary to make
   8 your application and library trace through an active LTTng tracer. Here is a
   9 short quickstart guide of it.
  10
  11 Here are the currently supported architectures :
  12 x86
  13 (please add the ltt_trace_generic and ltt_register_generic system calls to
  14 other architectures as you need them : it will work magically)
  15
  16 * Compile your kernel with the latest LTTng patch. Make sure the option
  17   "Allow tracing from userspace" is _active_!
  18   See the QUICKSTART guide at http://ltt.polymtl.ca/ for details about how to
  19   setup a working tracer and viewer. See the genevent installation step : it is
  20   required for method #2 below.
  21
  22 * Extract the latest ltt-usertrace archive :
  23 su
  24 cd /usr/src
  25 wget http://ltt.polymtl.ca/packages/ltt-usertrace-x.x.tar.gz
  26 gzip -cd ltt-usertrace-x.x.tar.gz | tar xvof -
  27
  28 * Build the sample programs and install the headers and librairies into your
  29 system :
  30 su
  31 cd /usr/src/ltt-usertrace
  32 make
  33 make install
  34
  35 Feel free to look at the sample programs and the Makefile : they demonstrate
  36 very well the features of the usertrace package and how to use them.
  37
  38 * There are three ways to trace information from your application. The choice
  39   will principally depend on the trace data rate.
  40
  41 1) Easy way, but slow (printf style)
  42   See sample-printf.c for code example.
  43
  44 - Add the following statements to your program source (the define must come
  45   _before_ the includes!) :
  46
  47 #define LTT_TRACE
  48 #define LTT_BLOCKING 1
  49 #include <ltt/ltt-facility-user_generic.h>
  50 #include <ltt/ltt-facility-custom-user_generic.h>
  51
  52 Note the define of LTT_BLOCKING to 1 : if a trace buffer is full, your
  53 application will block. The default of this parameter is 0 (non blocking) :
  54 events are lost when trace buffer is full. The choice is up to you.
  55
  56 - Add something like the following sample line in your code. Note that this is a
  57   very standard format string, this is only a suggested presentation.
  58
  59 trace_user_generic_slow_printf("in: %s at: %s:%d: Counter value is: %u.",
  60                                __FILE__, __func__, __LINE__, count);
  61
  62 - Compile your application with at least these parameters to gcc (it is splitted
  63   on two lines, joined by a "\") :
  64 gcc -D LTT_SHOW_DEBUG -I /usr/src/usertrace-generic -o myapp myapp.c \
  65   /usr/src/usertrace-generic/ltt-facility-loader-user_generic.c
  66
  67 To see what the final result looks like :
  68 - Start tracing
  69 - Start your application
  70   ** You should see the following message when your program starts and the
  71   LTT_SHOW_DEBUG is defined :
  72     "LTT : ltt-facility-user_generic init in userspace"
  73     If you don't then you forgot to compile the facility loader in your
  74     application. If you find this output annoying, you can remove the
  75     "-D LTT_SHOW_DEBUG" gcc parameter, which will make the facility loader
  76     silent.
  77 - Stop tracing
  78 Then, to see only the user_generic events :
  79 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_generic"
  80
  81 It will show :
  82 user_generic.slow_printf: 35885.922829472 (/cpu_0), 15521, 7453,  SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 0." }
  83 user_generic.slow_printf: 35886.925685289 (/cpu_0), 15521, 7453,  SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 1." }
  84 ...
  85
  86
  87
  88 2) The second way to log events is still easy. The advantage is that it
  89    will make it easier to identify your data in the trace viewer afterward.
  90    Please read the comments in method 1) explained previously, as they
  91    are not repeated here.
  92    See sample.c and sample-thread-slow.c for code example.
  93
  94 - Go to the ltt-usertrace directory
  95 su
  96 cd /usr/src/ltt-usertrace
  97
  98 - Create your own facility (i.e. user_myfacility.xml).
  99   See the ones available in /usr/share/LinuxTraceToolkitViewer/facilities for
 100   examples.
 101   You facility _must_ be named following this standard : "user_*", where * is
 102   whatever you like. If it is not, it will be rejected by the kernel with a
 103   Operation not permitted (can be seen with the -D LTT_SHOW_DEBUG compilation
 104   parameter).
 105
 106 user_myfacility.xml:
 107
 108 <?xml version="1.0"?>
 109 <facility name="user_myfacility">
 110   <description>Sample facility</description>
 111   <event name="myevent">
 112     <description>Sample event</description>
 113     <field name="file"><string></field>
 114     <field name="function"><string></field>
 115     <field name="line"><int></field>
 116     <field name="firstval"><long></field>
 117     <field name="secondval"><pointer></field>
 118   </event>
 119 </facility>
 120
 121 - AN IMPORTANT STEP FOLLOWS :
 122   *copy* the user_myfacility.xml file in your system :
 123 su
 124 cp user_myfacility.xml /usr/share/LinuxTraceToolkitViewer/facilities
 125
 126 - Use genevent to create the c code and headers :
 127 su
 128 cd /tmp
 129 mkdir genevent
 130 cd genevent
 131 for a in /usr/share/LinuxTraceToolkitViewer/facilities/user_*.xml;
 132   do /usr/local/bin/genevent $a;
 133 done
 134 cd /usr/src/usertrace-generic
 135 cp /tmp/genevent/*load* .
 136 cd ltt
 137 cp /tmp/genevent/ltt-facility-id-user_myfacility.h .
 138 cp /tmp/genevent/ltt-facility-user_myfacility.h .
 139 cd ..
 140 make install
 141
 142 - Add the following statements to your program source (the define must come
 143   _before_ the includes!) :
 144
 145 #define LTT_TRACE
 146 #define LTT_BLOCKING 1
 147 #include <ltt/ltt-facility-user_myfacility.h>
 148
 149 - Add a call following the trace_user_myfacility_myevent function found in
 150   /usr/include/ltt/ltt-facility-user_myfacility.h in your program.
 151 For instance :
 152 trace_user_myfacility_myevent(__FILE__, __func__, __LINE__, 1234, (void*)0xF0F0F0F0);
 153
 154 - Compile your application with at least these parameters to gcc (it is splitted
 155   on two lines, joined by a "\") :
 156 gcc -I /usr/src/usertrace-generic -o myapp myapp.c \
 157   /usr/src/usertrace-generic/ltt-facility-loader-user_myfacility.c
 158
 159 To see what the final result looks like :
 160 - Start tracing
 161 - Start your application
 162 - Stop tracing
 163 Then, to see only the user_myfacility events :
 164 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_myfacility"
 165
 166 It will show, for example :
 167 user_myfacility.myevent: 39507.805584526 (/cpu_1), 15829, 15736,  SYSCALL { "myapp.c", "main", 8, 1234, 0xf0f0f0f0 }
 168
 169
 170 3) The third way to trace information from your application
 171
 172 This method is cleary the _FASTEST_. It is principally I/O (disk and memory)
 173 bound. It will create a companion process for each of you program's thread which
 174 will dump the tracing information into /tmp/ltt-usertrace.
 175
 176 See sample-highspeed.c and sample-thread-fast.c for code example.
 177
 178 - Add the following statements to your program source (the define must come
 179   _before_ the includes!) :
 180
 181 #define LTT_TRACE
 182 #define LTT_TRACE_FAST
 183 #include <ltt/ltt-facility-user_myfacility.h>
 184
 185 - Add a call following the trace_user_myfacility_myevent function found in
 186   /usr/include/ltt/ltt-facility-user_myfacility.h in your program.
 187 For instance :
 188 trace_user_myfacility_myevent(__FILE__, __func__, __LINE__, 1234, (void*)0xF0F0F0F0);
 189
 190 - Compile your application with at least these parameters to gcc (it is splitted
 191   on two lines, joined by a "\") :
 192 gcc -lltt-usertrace-fast -I /usr/src/usertrace-generic -o myapp myapp.c \
 193   /usr/src/usertrace-generic/ltt-facility-loader-user_myfacility.c
 194
 195 It requires a supplementary operation when you take the trace :
 196 - Start tracing (with lttctl)
 197 - Start your application
 198 - Let your application run...
 199 - Stop tracing
 200 - Move or copy /tmp/ltt-usertrace info your trace.
 201 i.e., if your trace is in /tmp/trace1 :
 202 su
 203 mv /tmp/ltt-usertrace /tmp/trace1
 204
 205
 206 Then, to see only the user_myfacility events :
 207 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_myfacility"
 208
 209 It will show, for example :
 210 user_myfacility.myevent: 39507.805584526 (/ltt-usertrace/process-26174.26174.39236180500380_0), 15829, 15736,  USER_MODE { "myapp.c", "main", 8, 1234, 0xf0f0f0f0 }
 211
 212
 213
 214 * Fun feature : function instrumentation
 215
 216 Here is how to generate a full trace of you program function calls.
 217 See the sample-instrument-fct.c example program.
 218
 219 - Compile your application with at least these parameters to gcc (it is splitted
 220   on two lines, joined by a "\") :
 221 gcc -g -finstrument-functions \
 222   -lltt-instrument-functions -o myapp myapp.c
 223
 224 To see what the final result looks like :
 225 - Start tracing
 226 - Start your application
 227 - Stop tracing
 228 Then, to see only the function_entry and function_exit events :
 229 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_generic & (event.name=function_entry & event.name=function_exit)"
 230
 231 It will show, for example :
 232 user_generic.function_entry: 59329.709939111 (/ltt-usertrace/process-26202.0.39949996866578_0), 19250, 18581,  USER_MODE { 0x8048454, 0x80484c2 }
 233 user_generic.function_exit: 59329.709944613 (/ltt-usertrace/process-26202.0.39949996866578_0), 19250, 18581,  USER_MODE { 0x8048454, 0x80484c2 }
 234
 235 you can then use (from the binutils package)
 236 addr2line -e sample-instrument-fct -i -f 0x8048454
 237 Which shows :
 238 test_function
 239 /usr/src/usertrace-generic/sample-instrument-fct.c:12
 240
 241 The lookup in LTTV through libbfd has not been implemented yet.
 242
 243