tor

The Tor anonymity network
git clone https://git.dasho.dev/tor.git
Log | Files | Refs | README | LICENSE

events.h (2661B)

      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) */