[tor-commits] [tor/master] trace: Comments and configure fix

[nickm at torproject.org]

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

    trace: Comments and configure fix
    
    Signed-off-by: David Goulet <dgoulet at 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