commit c31d469f3734b0d60786deb2be9dafb3225755c3 Author: David Goulet dgoulet@torproject.org Date: Wed Jan 15 10:55:07 2020 -0500

trace: Comments and configure fix

Signed-off-by: David Goulet dgoulet@torproject.org --- configure.ac | 8 ++++---- src/lib/trace/events.h | 25 ++++++++++++++++++++++++- 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/configure.ac b/configure.ac index 8f47ff77b..cd014268b 100644 --- a/configure.ac +++ b/configure.ac @@ -2768,16 +2768,16 @@ test "x$enable_oss_fuzz" = "xyes" && value=1 || value=0 PPRINT_PROP_BOOL([OSS-Fuzz support (--enable-oss-fuzz)], $value)

AS_ECHO -PPRINT_SUBTITLE([Tracing]) +PPRINT_SUBTITLE([Tracing (--enable-tracing-instrumentation-<type>)])

test "x$enable_tracing_instrumentation_log_debug" = "xyes" && value=1 || value=0 -PPRINT_PROP_BOOL([Tracepoints to log_debug() (--enable-tracing-instrumentation-log-debug)], $value) +PPRINT_PROP_BOOL([Tracepoints to log_debug() (log-debug)], $value)

test "x$enable_tracing_instrumentation_usdt" = "xyes" && value=1 || value=0 -PPRINT_PROP_BOOL([USDT Instrumentation (--enable-tracing-instrumentation-usdt)], $value) +PPRINT_PROP_BOOL([USDT Instrumentation (usdt)], $value)

test "x$enable_tracing_instrumentation_lttng" = "xyes" && value=1 || value=0 -PPRINT_PROP_BOOL([LTTng Instrumentation (--enable-tracing-instrumentation-lttng)], $value) +PPRINT_PROP_BOOL([LTTng Instrumentation (lttng)], $value)

AS_ECHO PPRINT_SUBTITLE([Install Directories]) diff --git a/src/lib/trace/events.h b/src/lib/trace/events.h index 8cc0136b0..4a8078bf3 100644 --- a/src/lib/trace/events.h +++ b/src/lib/trace/events.h @@ -9,7 +9,30 @@ #ifndef TOR_LIB_TRACE_EVENTS_H #define TOR_LIB_TRACE_EVENTS_H

-/* XXX: DOCDOC once framework is stable. */ +/* + * A tracepoint signature is defined as follow: + * + * tor_trace(<subsystem>, <event_name>, <args>...) + * + * If tracing is enabled, the tor_trace() macro is mapped to all possible + * instrumentations (defined below). Each instrumentation type MUST define a + * top level macro (TOR_TRACE_<type>) so it can be inserted into each + * tracepoint. + * + * In case no tracing is enabled (HAVE_TRACING), tracepoints are NOP and thus + * have no execution cost. + * + * Currently, three types of instrumentation are supported: + * + * log-debug: Every tracepoints is mapped to a log_debug() statement. + * + * User Statically-Defined Tracing (USDT): Probes that can be used with perf, + * dtrace, SystemTap, DTrace and BPF Compiler Collection (BCC). + * + * LTTng-UST: Probes for the LTTng Userspace Tracer. If USDT interface + * (sdt.h) is available, the USDT probes are also generated by LTTng thus + * enabling this instrumentation provides both probes. + */

#ifdef HAVE_TRACING