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