src/lib/trace/events.h

   1 /* Copyright (c) 2017-2021, The Tor Project, Inc. */
   2 /* See LICENSE for licensing information */
   3
   4 /**
   5  * \file events.h
   6  * \brief Header file for Tor tracing instrumentation definition.
   7  **/
   8
   9 #ifndef TOR_LIB_TRACE_EVENTS_H
  10 #define TOR_LIB_TRACE_EVENTS_H
  11
  12 #include "orconfig.h"
  13
  14 /*
  15  * A tracepoint signature is defined as follow:
  16  *
  17  *    tor_trace(<subsystem>, <event_name>, <args>...)
  18  *
  19  * If tracing is enabled, the tor_trace() macro is mapped to all possible
  20  * instrumentations (defined below). Each instrumentation type MUST define a
  21  * top level macro (TOR_TRACE_<type>) so it can be inserted into each
  22  * tracepoint.
  23  *
  24  * In case no tracing is enabled (HAVE_TRACING), tracepoints are NOP and thus
  25  * have no execution cost.
  26  *
  27  * Currently, three types of instrumentation are supported:
  28  *
  29  *  log-debug: Every tracepoints is mapped to a log_debug() statement.
  30  *
  31  *  User Statically-Defined Tracing (USDT): Probes that can be used with perf,
  32  *  dtrace, SystemTap, DTrace and BPF Compiler Collection (BCC).
  33  *
  34  *  LTTng-UST: Probes for the LTTng Userspace Tracer. If USDT interface
  35  *  (sdt.h) is available, the USDT probes are also generated by LTTng thus
  36  *  enabling this instrumentation provides both probes.
  37  */
  38
  39 /** Helper to disambiguate these identifiers in the code base. They should
  40  * only be used with tor_trace() like so:
  41  *
  42  *    tor_trace(TR_SUBSYS(circuit), TR_EV(opened), ...);
  43  */
  44
  45 #define TR_SUBSYS(name) tor_ ## name
  46 #define TR_EV(name) name
  47
  48 #ifdef HAVE_TRACING
  49
  50 #define tor_trace(subsystem, event_name, ...)                       \
  51   do {                                                              \
  52     TOR_TRACE_LOG_DEBUG(subsystem, event_name);             \
  53     TOR_TRACE_USDT(subsystem, event_name, ## __VA_ARGS__);  \
  54     TOR_TRACE_LTTNG(subsystem, event_name, ## __VA_ARGS__); \
  55   } while (0)
  56
  57 /* This corresponds to the --enable-tracing-instrumentation-log-debug
  58  * configure option which maps all tracepoints to a log_debug() statement. */
  59 #include "lib/trace/debug.h"
  60
  61 /* This corresponds to the --enable-tracing-instrumentation-usdt configure
  62  * option which will generate USDT probes for each tracepoints. */
  63 #include "lib/trace/usdt/usdt.h"
  64
  65 /* This corresponds to the --enable-tracing-instrumentation-lttng configure
  66  * option which will generate LTTng probes for each tracepoints. */
  67 #include "lib/trace/lttng/lttng.h"
  68
  69 #else /* !defined(HAVE_TRACING) */
  70
  71 /* Reaching this point, tracing is disabled thus we NOP every tracepoints
  72  * declaration so we have no execution cost at runtime. */
  73 #define tor_trace(subsystem, name, ...)
  74
  75 #endif /* defined(HAVE_TRACING) */
  76
  77 #endif /* !defined(TOR_LIB_TRACE_EVENTS_H) */