usertrace-generic/README

   1
   2 LTTng usertrace generic 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_* system calls to other architectures as you need them : it
  14 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 usertrace-generic archive :
  23 su
  24 cd /usr/src
  25 wget http://ltt.polymtl.ca/packages/usertrace-generic-x.x.tar.gz
  26 gzip -cd usertrace-generic-x.x.tar.gz | tar xvof -
  27
  28 * Build the sample programs and install the headers into your system :
  29 su
  30 cd /usr/src/usertrace-generic
  31 make
  32 make install
  33
  34 * There are two ways to trace information from your application :
  35
  36 1) Easy way, but slow (printf style)
  37   See sample-printf.c for code example.
  38
  39 - Add the following statements to your program source (the define must come
  40   _before_ the includes!) :
  41
  42 #define LTT_TRACE
  43 #define LTT_BLOCKING 1
  44 #include <ltt/ltt-facility-user_generic.h>
  45 #include <ltt/ltt-facility-custom-user_generic.h>
  46
  47 Note the define of LTT_BLOCKING to 1 : if a trace buffer is full, your
  48 application will block. The default of this parameter is 0 (non blocking) :
  49 events are lost when trace buffer is full. The choice is up to you.
  50
  51 - Add something like the following sample line in your code. Note that this is a
  52   very standard format string, this is only a suggested presentation.
  53
  54 trace_user_generic_slow_printf("in: %s at: %s:%d: Counter value is: %u.",
  55                                __FILE__, __func__, __LINE__, count);
  56
  57 - Compile your application with at least these parameters to gcc (it is splitted
  58   on two lines, joined by a "\") :
  59 gcc -D LTT_SHOW_DEBUG -I /usr/src/usertrace-generic -o myapp myapp.c \
  60   /usr/src/usertrace-generic/ltt-facility-loader-user_generic.c
  61
  62 To see what the final result looks like :
  63 - Start tracing
  64 - Start your application
  65   ** You should see the following message when your program starts and the
  66   LTT_SHOW_DEBUG is defined :
  67     "LTT : ltt-facility-user_generic init in userspace"
  68     If you don't then you forgot to compile the facility loader in your
  69     application. If you find this output annoying, you can remove the
  70     "-D LTT_SHOW_DEBUG" gcc parameter, which will make the facility loader
  71     silent.
  72 - Stop tracing
  73 Then, to see only the user_generic events :
  74 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_generic"
  75
  76 It will show :
  77 user_generic.slow_printf: 35885.922829472 (/cpu_0), 15521, 7453,  SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 0." }
  78 user_generic.slow_printf: 35886.925685289 (/cpu_0), 15521, 7453,  SYSCALL { "in: sample-printf.c at: main:18: Counter value is: 1." }
  79 ...
  80
  81
  82
  83 2) The second way to log events is still easy, yet faster. It requires creating
  84    your own XML description of your data structures. It will make it easier to
  85    identify your data in the trace. Please read the comments in method 1)
  86    explained previously, as they are not repeated here.
  87    See sample.c for code example.
  88
  89 - Go to the usertrace-generic directory
  90 su
  91 cd /usr/src/usertrace-generic
  92
  93 - Create your own facility (i.e. user_myfacility.xml).
  94   See the ones available in /usr/share/LinuxTraceToolkitViewer/facilities for
  95   examples.
  96   You facility _must_ be named following this standard : "user_*", where * is
  97   whatever you like. If it is not, it will be rejected by the kernel with a
  98   Operation not permitted (can be seen with the -D LTT_SHOW_DEBUG compilation
  99   parameter).
 100
 101 user_myfacility.xml:
 102
 103 <facility name="user_myfacility">
 104   <description>Sample facility</description>
 105   <event name="myevent">
 106     <description>Sample event</description>
 107     <field name="file"><string></field>
 108     <field name="function"><string></field>
 109     <field name="line"><int></field>
 110     <field name="firstval"><long></field>
 111     <field name="secondval"><pointer></field>
 112   </event>
 113 </facility>
 114
 115 - AN IMPORTANT STEP FOLLOWS :
 116   *copy* the user_myfacility.xml file in your system :
 117 su
 118 cp user_myfacility.xml /usr/share/LinuxTraceToolkitViewer/facilities
 119
 120 - Use genevent to create the c code and headers :
 121 su
 122 cd /tmp
 123 mkdir genevent
 124 cd genevent
 125 for a in /usr/share/LinuxTraceToolkitViewer/facilities/user_*.xml;
 126   do /usr/local/bin/genevent $a;
 127 done
 128 cd /usr/src/usertrace-generic
 129 cp /tmp/genevent/*load* .
 130 cd ltt
 131 cp /tmp/genevent/ltt-facility-id-user_myfacility.h .
 132 cp /tmp/genevent/ltt-facility-user_myfacility.h .
 133 cd ..
 134 make install
 135
 136 - Add the following statements to your program source (the define must come
 137   _before_ the includes!) :
 138
 139 #define LTT_TRACE
 140 #define LTT_BLOCKING 1
 141 #include <ltt/ltt-facility-user_myfacility.h>
 142
 143 - Add a call following the trace_user_myfacility_myevent function found in
 144   /usr/include/ltt/ltt-facility-user_myfacility.h in your program.
 145 For instance :
 146 trace_user_myfacility_myevent(__FILE__, __func__, __LINE__, 1234, (void*)0xF0F0F0F0);
 147
 148 - Compile your application with at least these parameters to gcc (it is splitted
 149   on two lines, joined by a "\") :
 150 gcc -I /usr/src/usertrace-generic -o myapp myapp.c \
 151   /usr/src/usertrace-generic/ltt-facility-loader-user_myfacility.c
 152
 153 To see what the final result looks like :
 154 - Start tracing
 155 - Start your application
 156 - Stop tracing
 157 Then, to see only the user_myfacility events :
 158 lttv -m textDump -t /tmp/trace1 -e "event.facility=user_myfacility"
 159
 160 It will show, for example :
 161 user_myfacility.myevent: 39507.805584526 (/cpu_1), 15829, 15736,  SYSCALL { "myapp.c", "main", 8, 1234, 0xf0f0f0f0 }
 162
 163
 164