Tor 0.4.9.0-alpha-dev
events.h
Go to the documentation of this file.
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. */
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) */
Macros for debugging our event-trace support.
Header file for lttng.c.