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 <facility name="user_myfacility">
 109   <description>Sample facility</description>
 110   <event name="myevent">
 111     <description>Sample event</description>
 112     <field name="file"><string></field>
 113     <field name="function"><string></field>
 114     <field name="line"><int></field>
 115     <field name="firstval"><long></field>
 116     <field name="secondval"><pointer></field>
 117   </event>
 118 </facility>
 119
 120 - AN IMPORTANT STEP FOLLOWS :
 121   *copy* the user_myfacility.xml file in your system :
 122 su
 123 cp user_myfacility.xml /usr/share/LinuxTraceToolkitViewer/facilities
 124
 125 - Use genevent to create the c code and headers :
 126 su
 127 cd /tmp
 128 mkdir genevent
 129 cd genevent
 130 for a in /usr/share/LinuxTraceToolkitViewer/facilities/user_*.xml;
 131   do /usr/local/bin/genevent $a;
 132 done
 133 cd /usr/src/usertrace-generic
 134 cp /tmp/genevent/*load* .
 135 cd ltt
 136 cp /tmp/genevent/ltt-facility-id-user_myfacility.h .
 137 cp /tmp/genevent/ltt-facility-user_myfacility.h .
 138 cd ..
 139 make install
 140
 141 - Add the following statements to your program source (the define must come
 142   _before_ the includes!) :
 143
 144 #define LTT_TRACE
 145 #define LTT_BLOCKING 1
 146 #include <ltt/ltt-facility-user_myfacility.h>
 147
 148 - Add a call following the trace_user_myfacility_myevent function found in
 149   /usr/include/ltt/ltt-facility-user_myfacility.h in your program.
 150 For instance :
 151 trace_user_myfacility_myevent(__FILE__, __func__, __LINE__, 1234, (void*)0xF0F0F0F0);
 152
 153 - Compile your application with at least these parameters to gcc (it is splitted
 154   on two lines, joined by a "\") :
 155 gcc -I /usr/src/usertrace-generic -o myapp myapp.c \
 156   /usr/src/usertrace-generic/ltt-facility-loader-user_myfacility.c
 157
 158 To see what the final result looks like :
 159 - Start tracing
 160 - Start your application
 161 - Stop tracing
 162 Then, to see only the user_myfacility events :
 163 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_myfacility"
 164
 165 It will show, for example :
 166 user_myfacility.myevent: 39507.805584526 (/cpu_1), 15829, 15736,  SYSCALL { "myapp.c", "main", 8, 1234, 0xf0f0f0f0 }
 167
 168
 169 3) The third way to trace information from your application
 170
 171 This method is cleary the _FASTEST_. It is principally I/O (disk and memory)
 172 bound. It will create a companion process for each of you program's thread which
 173 will dump the tracing information into /tmp/ltt-usertrace.
 174
 175 See sample-highspeed.c and sample-thread-fast.c for code example.
 176
 177 - Add the following statements to your program source (the define must come
 178   _before_ the includes!) :
 179
 180 #define LTT_TRACE
 181 #define LTT_TRACE_FAST
 182 #include <ltt/ltt-facility-user_myfacility.h>
 183
 184 - Add a call following the trace_user_myfacility_myevent function found in
 185   /usr/include/ltt/ltt-facility-user_myfacility.h in your program.
 186 For instance :
 187 trace_user_myfacility_myevent(__FILE__, __func__, __LINE__, 1234, (void*)0xF0F0F0F0);
 188
 189 - Compile your application with at least these parameters to gcc (it is splitted
 190   on two lines, joined by a "\") :
 191 gcc -lltt-usertrace-fast -I /usr/src/usertrace-generic -o myapp myapp.c \
 192   /usr/src/usertrace-generic/ltt-facility-loader-user_myfacility.c
 193
 194 It requires a supplementary operation when you take the trace :
 195 - Start tracing (with lttctl)
 196 - Start your application
 197 - Let your application run...
 198 - Stop tracing
 199 - Move or copy /tmp/ltt-usertrace info your trace.
 200 i.e., if your trace is in /tmp/trace1 :
 201 su
 202 mv /tmp/ltt-usertrace /tmp/trace1
 203
 204
 205 Then, to see only the user_myfacility events :
 206 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_myfacility"
 207
 208 It will show, for example :
 209 user_myfacility.myevent: 39507.805584526 (/ltt-usertrace/process-26174.26174.39236180500380_0), 15829, 15736,  USER_MODE { "myapp.c", "main", 8, 1234, 0xf0f0f0f0 }
 210
 211
 212
 213 * Fun feature : function instrumentation
 214
 215 Here is how to generate a full trace of you program function calls.
 216 See the sample-instrument-fct.c example program.
 217
 218 - Compile your application with at least these parameters to gcc (it is splitted
 219   on two lines, joined by a "\") :
 220 gcc -g -finstrument-functions \
 221   -lltt-instrument-functions -o myapp myapp.c
 222
 223 To see what the final result looks like :
 224 - Start tracing
 225 - Start your application
 226 - Stop tracing
 227 Then, to see only the function_entry and function_exit events :
 228 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_generic & (event.name=function_entry & event.name=function_exit)"
 229
 230 It will show, for example :
 231 user_generic.function_entry: 59329.709939111 (/ltt-usertrace/process-26202.0.39949996866578_0), 19250, 18581,  USER_MODE { 0x8048454, 0x80484c2 }
 232 user_generic.function_exit: 59329.709944613 (/ltt-usertrace/process-26202.0.39949996866578_0), 19250, 18581,  USER_MODE { 0x8048454, 0x80484c2 }
 233
 234 you can then use (from the binutils package)
 235 addr2line -e sample-instrument-fct -i -f 0x8048454
 236 Which shows :
 237 test_function
 238 /usr/src/usertrace-generic/sample-instrument-fct.c:12
 239
 240 The lookup in LTTV through libbfd has not been implemented yet.
 241
 242