[tor-commits] [tor/master] doc: Document circuit subsystem tracing events

[ahf at torproject.org]

commit 9c653e58b41f12c58da060669fa148172f20127a
Author: David Goulet <dgoulet at torproject.org>
Date:   Wed Jul 15 09:44:12 2020 -0400

    doc: Document circuit subsystem tracing events
    
    Create a doc/tracing/ directory to contain a top level README.md which is the
    previously named Tracing.md and add the EventsCircuit.md which describes the
    circuit subsystem tracing events in depth.
    
    Closes #40036
    
    Signed-off-by: David Goulet <dgoulet at torproject.org>
---
 changes/ticket40036                           |   3 +
 doc/HACKING/tracing/EventsCircuit.md          | 139 ++++++++++++++++++++++++++
 doc/HACKING/{Tracing.md => tracing/README.md} |   0
 3 files changed, 142 insertions(+)

diff --git a/changes/ticket40036 b/changes/ticket40036
new file mode 100644
index 0000000000..3586e44694
--- /dev/null
+++ b/changes/ticket40036
@@ -0,0 +1,3 @@
+  o Documentation (tracing):
+    - Document in depth the circuit subsystem trace events in the new
+      doc/tracing/EventsCircuit.md. Closes ticket 40036.
diff --git a/doc/HACKING/tracing/EventsCircuit.md b/doc/HACKING/tracing/EventsCircuit.md
new file mode 100644
index 0000000000..42abdda856
--- /dev/null
+++ b/doc/HACKING/tracing/EventsCircuit.md
@@ -0,0 +1,139 @@
+# Circuit Subsystem Trace Events
+
+The circuit subsystem emits a series of tracing events related to a circuit
+object life cycle and its state change.
+
+This document describes each event as in what data they record and what they
+represent.
+
+## Background
+
+There are two types of circuits: origin and OR (onion router). Both of them
+are derived from a base object called a general circuit.
+
+- Origin circuits are the ones initiated by tor itself so client or onion
+  service circuits for instance.
+
+- OR circuits are the ones going through us that we have not initiated and
+  thus only seen by relays.
+
+Many operations are done on the base (general) circuit, and some are specific
+to an origin or OR. The following section describes each of them by circuit
+type.
+
+## Trace Events
+
+For the LTTng tracer, the subsystem name of these events is: `tor_circuit`.
+
+Also, unless specified otherwise, every event emits a common set of parameters
+thus they should always be expected in the following order:
+
+- `circ_id`: For an origin circuit, this is the global circuit identifier used
+  in a cell. For an OR circuit, the value is 0.
+
+- `purpose`: Purpose of the circuit as in what it is used for. Note that this
+  can change during the lifetime of a circuit. See `CIRCUIT_PURPOSE_*` in
+  `core/or/circuitlist.h` for an exhaustive list of the possible values.
+
+- `state`: State of a circuit. This changes during the lifetime of a circuit.
+  See `CIRCUIT_STATE_*` in `core/or/circuitlist.h` for an exhaustive list of
+  the possible values.
+
+Now, the tracing events.
+
+### General Circuit (`circuit_t`)
+
+The following events are triggered for the base circuit object and thus apply
+to all types of circuits.
+
+  * `free`: A circuit object is freed that is memory is released and not
+    usable anymore. After this event, no more events will be emitted for the
+    specific circuit object.
+
+  * `mark_for_close`: A circuit object is marked for close that is scheduled
+    to be closed in a later mainloop periodic event.
+
+    Extra parameters:
+
+    - `end_reason`: Reason why the circuit is closed. Tor often changes that
+      reason to something generic sometimes in order to avoid leaking internal
+      reasons to the end point. Thus, this value can be different from
+      orig_close_reason.
+
+    - `orig_close_reason`: Original reason why the circuit is closed. That
+      value never changes and contains the internal reason why we close it. It
+      is **never** this reason that is sent back on the circuit.
+
+  * `change_purpose`: Purpose change.
+
+    Extra parameters:
+
+    (`purpose` parameter is not present)
+
+    - `old_purpose`: Previous purpose that is no longer.
+
+    - `new_purpose`: New purpose assigned to the circuit.
+
+  * `change_state`: State change.
+
+    Extra parameters:
+
+    (`state` parameter is not present)
+
+    - `old_state`: Previous state that is no longer.
+
+    - `new_state`: New state assigned to the circuit.
+
+### Origin Circuit (`origin_circuit_t`)
+
+The following events are triggered only for origin circuits.
+
+  * `new_origin`: New origin circuit has been created meaning it has been
+    newly allocated, initialized and added to the global list.
+
+  * `establish`: Circuit is being established. This is the initial first step
+    where the path was selected and a connection to the first hop has been
+    launched.
+
+  * `cannibalized`: Circuit has been cannibalized. This happens when we have
+    an already opened unused circuit (preemptive circuits) and it was picked.
+
+  * `first_onion_skin`: First onion skin was sent that is the handshake with
+    the first hop.
+
+    Extra parameters:
+
+    - `fingerprint`: Identity digest (RSA) of the first hop.
+
+  * `intermediate_onion_skin`: An intermediate onion skin was sent which can
+    be why any hops after the first one. There is thus `N - 1` of these events
+    where `N` is the total number of hops in the path.
+
+    Extra parameters:
+
+    - `fingerprint`: Identity digest (RSA) of the next hop.
+
+  * `opened`: Circuit just became opened which means that all hops down the
+    path have negotiated the handshake between them and us and the circuit is
+    now ready to send cells.
+
+  * `timeout`: Circuit has timed out that is we waited too long for the
+    circuit to be built.
+
+  * `idle_timeout`: Circuit has timed out due to idleness. This is controlled
+    by the MaxCircuitDirtiness parameter which is 10 min by default.
+
+For the common use case of a 3-hop circuit, the following events should be
+seen in this order:
+
+  `new_origin` -> `establish` -> `first_onion_skin` ->
+  `intermediate_onion_skin` -> `intermediate_onion_skin` -> `opened`
+
+### OR Circuit (`or_circuit_t`)
+
+The following events are triggered only for OR circuits. For each of them, the
+`circ_id` parameter is not present since it would always be 0. The `purpose`
+and `state` remain.
+
+  * `new_or`: New OR circuit has been created meaning it has been newly
+    allocated, initialized and added to the global list.
diff --git a/doc/HACKING/Tracing.md b/doc/HACKING/tracing/README.md
similarity index 100%
rename from doc/HACKING/Tracing.md
rename to doc/HACKING/tracing/README.md