tor/doc/HACKING/tracing/EventsCircuit.md

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.