doc/HACKING/Tracing.md

   1 # Tracing #
   2
   3 This document describes how the event tracing subsystem works in tor so
   4 developers can add events to the code base but also hook them to an event
   5 tracing framework.
   6
   7 ## Basics ###
   8
   9 Event tracing is separated in two concepts, trace events and a tracer. The
  10 tracing subsystem can be found in `src/trace`. The `events.h` header file is
  11 the main file that maps the different tracers to trace events.
  12
  13 ### Events ###
  14
  15 A trace event is basically a function from which we can pass any data that
  16 we want to collect. In addition, we specify a context for the event such as
  17 a subsystem and an event name.
  18
  19 A trace event in tor has the following standard format:
  20
  21         tor_trace(subsystem, event\_name, args...)
  22
  23 The `subsystem` parameter is the name of the subsytem the trace event is in.
  24 For example that could be "scheduler" or "vote" or "hs". The idea is to add
  25 some context to the event so when we collect them we know where it's coming
  26 from. The `event_name` is the name of the event which helps a lot with
  27 adding some semantic to the event. Finally, `args` is any number of
  28 arguments we want to collect.
  29
  30 Here is an example of a possible tracepoint in main():
  31
  32         tor_trace(main, init_phase, argc)
  33
  34 The above is a tracepoint in the `main` subsystem with `init_phase` as the
  35 event name and the `int argc` is passed to the event as well.
  36
  37 How `argc` is collected or used has nothing to do with the instrumentation
  38 (adding trace events to the code). It is the work of the tracer so this is why
  39 the trace events and collection framework (tracer) are decoupled. You _can_
  40 have trace events without a tracer.
  41
  42 ### Tracer ###
  43
  44 In `src/trace/events.h`, we map the `tor_trace()` function to the right
  45 tracer. A tracer support is only enabled at compile time. For instance, the
  46 file `src/trace/debug.h` contains the mapping of the generic tracing function
  47 `tor_trace()` to the `log_debug()` function. More specialized function can be
  48 mapped depending on the tracepoint.
  49
  50 ## Build System ##
  51
  52 This section describes how it is integrated into the build system of tor.
  53
  54 By default, every tracing events are disabled in tor that is `tor_trace()`
  55 is a NOP.
  56
  57 To enable a tracer, there is a configure option on the form of:
  58
  59         --enable-tracing-<tracer>
  60
  61 We have an option that will send every trace events to a `log_debug()` (as
  62 mentionned above) which will print you the subsystem and name of the event but
  63 not the arguments for technical reasons. This is useful if you want to quickly
  64 see if your trace event is being hit or well written. To do so, use this
  65 configure option:
  66
  67         --enable-tracing-debug
  68
  69 ## Instrument Tor ##
  70
  71 This is pretty easy. Let's say you want to add a trace event in
  72 `src/or/rendcache.c`, you only have to add this include statement:
  73
  74         #include "trace/events.h"
  75
  76 Once done, you can add as many as you want `tor_trace()` that you need.
  77 Please use the right subsystem (here it would be `hs`) and a unique name that
  78 tells what the event is for. For example:
  79
  80         tor_trace(hs, store_desc_as_client, desc, desc_id);
  81
  82 If you look in `src/trace/events.h`, you'll see that if tracing is enabled it
  83 will be mapped to a function called:
  84
  85         tor_trace_hs_store_desc_as_client(desc, desc_id)
  86
  87 And the point of all this is for that function to be defined in a new file
  88 that you might want to add named `src/trace/hs.{c|h}` which would defined how
  89 to collect the data for the `tor_trace_hs_store_desc_as_client()` function
  90 like for instance sending it to a `log_debug()` or do more complex operations
  91 or use a userspace tracer like LTTng (https://lttng.org).