1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
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.
|
