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/usertrace-generic
  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 :
  39
  40 1) Easy way, but slow (printf style)
  41   See sample-printf.c for code example.
  42
  43 - Add the following statements to your program source (the define must come
  44   _before_ the includes!) :
  45
  46 #define LTT_TRACE
  47 #define LTT_BLOCKING 1
  48 #include <ltt/ltt-facility-user_generic.h>
  49 #include <ltt/ltt-facility-custom-user_generic.h>
  50
  51 Note the define of LTT_BLOCKING to 1 : if a trace buffer is full, your
  52 application will block. The default of this parameter is 0 (non blocking) :
  53 events are lost when trace buffer is full. The choice is up to you.
  54
  55 - Add something like the following sample line in your code. Note that this is a
  56   very standard format string, this is only a suggested presentation.
  57
  58 trace_user_generic_slow_printf("in: %s at: %s:%d: Counter value is: %u.",
  59                                __FILE__, __func__, __LINE__, count);
  60
  61 - Compile your application with at least these parameters to gcc (it is splitted
  62   on two lines, joined by a "\") :
  63 gcc -D LTT_SHOW_DEBUG -I /usr/src/usertrace-generic -o myapp myapp.c \
  64   /usr/src/usertrace-generic/ltt-facility-loader-user_generic.c
  65
  66 To see what the final result looks like :
  67 - Start tracing
  68 - Start your application
  69   ** You should see the following message when your program starts and the
  70   LTT_SHOW_DEBUG is defined :
  71     "LTT : ltt-facility-user_generic init in userspace"
  72     If you don't then you forgot to compile the facility loader in your
  73     application. If you find this output annoying, you can remove the
  74     "-D LTT_SHOW_DEBUG" gcc parameter, which will make the facility loader
  75     silent.
  76 - Stop tracing
  77 Then, to see only the user_generic events :
  78 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_generic"
  79
  80 It will show :
  81 user_generic.slow_printf: 35885.922829472 (/cpu_0), 15521, 7453,  SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 0." }
  82 user_generic.slow_printf: 35886.925685289 (/cpu_0), 15521, 7453,  SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 1." }
  83 ...
  84
  85
  86
  87 2) The second way to log events is still easy, yet faster. It requires creating
  88    your own XML description of your data structures. It will make it easier to
  89    identify your data in the trace. Please read the comments in method 1)
  90    explained previously, as they are not repeated here.
  91    See sample.c for code example.
  92
  93 - Go to the usertrace-generic directory
  94 su
  95 cd /usr/src/usertrace-generic
  96
  97 - Create your own facility (i.e. user_myfacility.xml).
  98   See the ones available in /usr/share/LinuxTraceToolkitViewer/facilities for
  99   examples.
 100   You facility _must_ be named following this standard : "user_*", where * is
 101   whatever you like. If it is not, it will be rejected by the kernel with a
 102   Operation not permitted (can be seen with the -D LTT_SHOW_DEBUG compilation
 103   parameter).
 104
 105 user_myfacility.xml:
 106
 107 <facility name="user_myfacility">
 108   <description>Sample facility</description>
 109   <event name="myevent">
 110     <description>Sample event</description>
 111     <field name="file"><string></field>
 112     <field name="function"><string></field>
 113     <field name="line"><int></field>
 114     <field name="firstval"><long></field>
 115     <field name="secondval"><pointer></field>
 116   </event>
 117 </facility>
 118
 119 - AN IMPORTANT STEP FOLLOWS :
 120   *copy* the user_myfacility.xml file in your system :
 121 su
 122 cp user_myfacility.xml /usr/share/LinuxTraceToolkitViewer/facilities
 123
 124 - Use genevent to create the c code and headers :
 125 su
 126 cd /tmp
 127 mkdir genevent
 128 cd genevent
 129 for a in /usr/share/LinuxTraceToolkitViewer/facilities/user_*.xml;
 130   do /usr/local/bin/genevent $a;
 131 done
 132 cd /usr/src/usertrace-generic
 133 cp /tmp/genevent/*load* .
 134 cd ltt
 135 cp /tmp/genevent/ltt-facility-id-user_myfacility.h .
 136 cp /tmp/genevent/ltt-facility-user_myfacility.h .
 137 cd ..
 138 make install
 139
 140 - Add the following statements to your program source (the define must come
 141   _before_ the includes!) :
 142
 143 #define LTT_TRACE
 144 #define LTT_BLOCKING 1
 145 #include <ltt/ltt-facility-user_myfacility.h>
 146
 147 - Add a call following the trace_user_myfacility_myevent function found in
 148   /usr/include/ltt/ltt-facility-user_myfacility.h in your program.
 149 For instance :
 150 trace_user_myfacility_myevent(__FILE__, __func__, __LINE__, 1234, (void*)0xF0F0F0F0);
 151
 152 - Compile your application with at least these parameters to gcc (it is splitted
 153   on two lines, joined by a "\") :
 154 gcc -I /usr/src/usertrace-generic -o myapp myapp.c \
 155   /usr/src/usertrace-generic/ltt-facility-loader-user_myfacility.c
 156
 157 To see what the final result looks like :
 158 - Start tracing
 159 - Start your application
 160 - Stop tracing
 161 Then, to see only the user_myfacility events :
 162 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_myfacility"
 163
 164 It will show, for example :
 165 user_myfacility.myevent: 39507.805584526 (/cpu_1), 15829, 15736,  SYSCALL { "myapp.c", "main", 8, 1234, 0xf0f0f0f0 }
 166
 167
 168 * Fun feature : function instrumentation
 169
 170 Here is how to generate a full trace of you program function calls.
 171 See the sample-instrument-fct.c example program.
 172
 173 - Compile your application with at least these parameters to gcc (it is splitted
 174   on two lines, joined by a "\") :
 175 gcc -g -finstrument-functions \
 176   -lltt-instrument-functions -o myapp myapp.c
 177
 178 To see what the final result looks like :
 179 - Start tracing
 180 - Start your application
 181 - Stop tracing
 182 Then, to see only the function_entry and function_exit events :
 183 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_generic & (event.name=function_entry & event.name=function_exit)"
 184
 185 It will show, for example :
 186 user_generic.function_entry: 59329.709939111 (/cpu_0), 19250, 18581,  SYSCALL { 0x8048454, 0x80484c2 }
 187 user_generic.function_exit: 59329.709944613 (/cpu_0), 19250, 18581,  SYSCALL { 0x8048454, 0x80484c2 }
 188
 189 you can then use (from the binutils package)
 190 addr2line -e sample-instrument-fct -i -f 0x8048454
 191 Which shows :
 192 test_function
 193 /usr/src/usertrace-generic/sample-instrument-fct.c:12
 194
 195 The lookup in LTTV through libbfd has not been implemented yet.
 196
 197