Tor  0.4.3.0-alpha-dev
Macros | Typedefs | Functions
circuitstats.h File Reference

Header file for circuitstats.c. More...

Go to the source code of this file.

Macros

#define CBT_NCIRCUITS_TO_OBSERVE   1000
 
#define CBT_BIN_WIDTH   ((build_time_t)50)
 
#define CBT_DEFAULT_NUM_XM_MODES   3
 
#define CBT_MIN_NUM_XM_MODES   1
 
#define CBT_MAX_NUM_XM_MODES   20
 
#define CBT_BUILD_ABANDONED   ((build_time_t)(INT32_MAX-1))
 
#define CBT_BUILD_TIME_MAX   ((build_time_t)(INT32_MAX))
 
#define CBT_SAVE_STATE_EVERY   10
 
#define CBT_DEFAULT_CLOSE_QUANTILE   95
 
#define CBT_MIN_CLOSE_QUANTILE   CBT_MIN_QUANTILE_CUTOFF
 
#define CBT_MAX_CLOSE_QUANTILE   CBT_MAX_QUANTILE_CUTOFF
 
#define CBT_DEFAULT_RECENT_CIRCUITS   20
 
#define CBT_MIN_RECENT_CIRCUITS   3
 
#define CBT_MAX_RECENT_CIRCUITS   1000
 
#define CBT_DEFAULT_MAX_RECENT_TIMEOUT_COUNT   (CBT_DEFAULT_RECENT_CIRCUITS*9/10)
 
#define CBT_MIN_MAX_RECENT_TIMEOUT_COUNT   3
 
#define CBT_MAX_MAX_RECENT_TIMEOUT_COUNT   10000
 
#define CBT_DEFAULT_MIN_CIRCUITS_TO_OBSERVE   100
 
#define CBT_MIN_MIN_CIRCUITS_TO_OBSERVE   1
 
#define CBT_MAX_MIN_CIRCUITS_TO_OBSERVE   10000
 
#define CBT_DEFAULT_QUANTILE_CUTOFF   80
 
#define CBT_MIN_QUANTILE_CUTOFF   10
 
#define CBT_MAX_QUANTILE_CUTOFF   99
 
#define CBT_DEFAULT_TEST_FREQUENCY   10
 
#define CBT_MIN_TEST_FREQUENCY   1
 
#define CBT_MAX_TEST_FREQUENCY   INT32_MAX
 
#define CBT_DEFAULT_TIMEOUT_MIN_VALUE   (1500)
 
#define CBT_MIN_TIMEOUT_MIN_VALUE   500
 
#define CBT_MAX_TIMEOUT_MIN_VALUE   INT32_MAX
 
#define CBT_DEFAULT_TIMEOUT_INITIAL_VALUE   (60*1000)
 
#define CBT_MIN_TIMEOUT_INITIAL_VALUE   CBT_MIN_TIMEOUT_MIN_VALUE
 
#define CBT_MAX_TIMEOUT_INITIAL_VALUE   INT32_MAX
 

Typedefs

typedef uint32_t build_time_t
 

Functions

const circuit_build_times_t * get_circuit_build_times (void)
 
circuit_build_times_t * get_circuit_build_times_mutable (void)
 
double get_circuit_build_close_time_ms (void)
 
double get_circuit_build_timeout_ms (void)
 
int circuit_build_times_disabled (const or_options_t *options)
 
int circuit_build_times_disabled_ (const or_options_t *options, int ignore_consensus)
 
int circuit_build_times_enough_to_compute (const circuit_build_times_t *cbt)
 
void circuit_build_times_update_state (const circuit_build_times_t *cbt, or_state_t *state)
 
int circuit_build_times_parse_state (circuit_build_times_t *cbt, or_state_t *state)
 
void circuit_build_times_count_timeout (circuit_build_times_t *cbt, int did_onehop)
 
int circuit_build_times_count_close (circuit_build_times_t *cbt, int did_onehop, time_t start_time)
 
void circuit_build_times_set_timeout (circuit_build_times_t *cbt)
 
int circuit_build_times_add_time (circuit_build_times_t *cbt, build_time_t time)
 
int circuit_build_times_needs_circuits (const circuit_build_times_t *cbt)
 
void circuit_build_times_handle_completed_hop (origin_circuit_t *circ)
 
int circuit_build_times_needs_circuits_now (const circuit_build_times_t *cbt)
 
void circuit_build_times_init (circuit_build_times_t *cbt)
 
void circuit_build_times_free_timeouts (circuit_build_times_t *cbt)
 
void circuit_build_times_new_consensus_params (circuit_build_times_t *cbt, networkstatus_t *ns)
 
double circuit_build_times_timeout_rate (const circuit_build_times_t *cbt)
 
double circuit_build_times_close_rate (const circuit_build_times_t *cbt)
 
void circuit_build_times_update_last_circ (circuit_build_times_t *cbt)
 
void circuit_build_times_mark_circ_as_measurement_only (origin_circuit_t *circ)
 
double circuit_build_times_quantile_cutoff (void)
 
int32_t circuit_build_times_initial_timeout (void)
 
void circuit_build_times_network_is_live (circuit_build_times_t *cbt)
 
int circuit_build_times_network_check_live (const circuit_build_times_t *cbt)
 
void circuit_build_times_network_circ_success (circuit_build_times_t *cbt)
 

Detailed Description

Header file for circuitstats.c.

Definition in file circuitstats.h.

Macro Definition Documentation

◆ CBT_BIN_WIDTH

#define CBT_BIN_WIDTH   ((build_time_t)50)

Width of the histogram bins in milliseconds

Definition at line 58 of file circuitstats.h.

◆ CBT_BUILD_ABANDONED

#define CBT_BUILD_ABANDONED   ((build_time_t)(INT32_MAX-1))

CBT_BUILD_ABANDONED is our flag value to represent a force-closed circuit (Aka a 'right-censored' pareto value).

Definition at line 69 of file circuitstats.h.

◆ CBT_DEFAULT_CLOSE_QUANTILE

#define CBT_DEFAULT_CLOSE_QUANTILE   95

How long to wait before actually closing circuits that take too long to build in terms of CDF quantile.

Definition at line 81 of file circuitstats.h.

◆ CBT_DEFAULT_MAX_RECENT_TIMEOUT_COUNT

#define CBT_DEFAULT_MAX_RECENT_TIMEOUT_COUNT   (CBT_DEFAULT_RECENT_CIRCUITS*9/10)

Maximum count of timeouts that finish the first hop in the past RECENT_CIRCUITS before calculating a new timeout.

This tells us whether to abandon timeout history and set the timeout back to whatever circuit_build_times_get_initial_timeout() gives us.

Definition at line 101 of file circuitstats.h.

◆ CBT_DEFAULT_MIN_CIRCUITS_TO_OBSERVE

#define CBT_DEFAULT_MIN_CIRCUITS_TO_OBSERVE   100

Minimum circuits before estimating a timeout

Definition at line 106 of file circuitstats.h.

◆ CBT_DEFAULT_NUM_XM_MODES

#define CBT_DEFAULT_NUM_XM_MODES   3

Number of modes to use in the weighted-avg computation of Xm

Definition at line 61 of file circuitstats.h.

◆ CBT_DEFAULT_QUANTILE_CUTOFF

#define CBT_DEFAULT_QUANTILE_CUTOFF   80

Cutoff percentile on the CDF for our timeout estimation.

Definition at line 111 of file circuitstats.h.

◆ CBT_DEFAULT_RECENT_CIRCUITS

#define CBT_DEFAULT_RECENT_CIRCUITS   20

How many circuits count as recent when considering if the connection has gone gimpy or changed.

Definition at line 89 of file circuitstats.h.

◆ CBT_DEFAULT_TEST_FREQUENCY

#define CBT_DEFAULT_TEST_FREQUENCY   10

How often in seconds should we build a test circuit

Definition at line 117 of file circuitstats.h.

◆ CBT_DEFAULT_TIMEOUT_INITIAL_VALUE

#define CBT_DEFAULT_TIMEOUT_INITIAL_VALUE   (60*1000)

Initial circuit build timeout in milliseconds

Definition at line 127 of file circuitstats.h.

◆ CBT_DEFAULT_TIMEOUT_MIN_VALUE

#define CBT_DEFAULT_TIMEOUT_MIN_VALUE   (1500)

Lowest allowable value for CircuitBuildTimeout in milliseconds

Definition at line 122 of file circuitstats.h.

◆ CBT_NCIRCUITS_TO_OBSERVE

#define CBT_NCIRCUITS_TO_OBSERVE   1000

Total size of the circuit timeout history to accumulate. 1000 is approx 2.5 days worth of continual-use circuits.

Definition at line 55 of file circuitstats.h.

◆ CBT_SAVE_STATE_EVERY

#define CBT_SAVE_STATE_EVERY   10

Save state every 10 circuits

Definition at line 73 of file circuitstats.h.

Typedef Documentation

◆ build_time_t

typedef uint32_t build_time_t

A build_time_t is milliseconds

Definition at line 25 of file circuitstats.h.

Function Documentation

◆ circuit_build_times_add_time()

int circuit_build_times_add_time ( circuit_build_times_t *  cbt,
build_time_t  btime 
)

Add a new build time value time to the set of build times. Time units are milliseconds.

circuit_build_times cbt is a circular array, so loop around when array is full.

Definition at line 760 of file circuitstats.c.

Referenced by circuit_build_times_count_close().

◆ circuit_build_times_close_rate()

double circuit_build_times_close_rate ( const circuit_build_times_t *  cbt)

Count the number of closed circuits in a set of cbt data.

Definition at line 1697 of file circuitstats.c.

◆ circuit_build_times_count_close()

int circuit_build_times_count_close ( circuit_build_times_t *  cbt,
int  did_onehop,
time_t  start_time 
)

Store a timeout as a synthetic value.

Returns true if the store was successful and we should possibly update our timeout estimate.

Definition at line 1719 of file circuitstats.c.

◆ circuit_build_times_count_timeout()

void circuit_build_times_count_timeout ( circuit_build_times_t *  cbt,
int  did_onehop 
)

Update timeout counts to determine if we need to expire our build time history due to excessive timeouts.

We do not record any actual time values at this stage; we are only interested in recording the fact that a timeout happened. We record the time values via circuit_build_times_count_close() and circuit_build_times_add_time().

Definition at line 1751 of file circuitstats.c.

◆ circuit_build_times_disabled()

int circuit_build_times_disabled ( const or_options_t options)

This function decides if CBT learning should be disabled. It returns true if one or more of the following conditions are met:

  1. If the cbtdisabled consensus parameter is set.
  2. If the torrc option LearnCircuitBuildTimeout is false.
  3. If we are a directory authority
  4. If we fail to write circuit build time history to our state file.
  5. If we are configured in Single Onion mode

Definition at line 121 of file circuitstats.c.

Referenced by circuit_build_times_count_close(), circuit_build_times_count_timeout(), circuit_build_times_handle_completed_hop(), circuit_build_times_init(), circuit_build_times_new_consensus_params(), circuit_build_times_parse_state(), and circuit_build_times_set_timeout().

◆ circuit_build_times_disabled_()

int circuit_build_times_disabled_ ( const or_options_t options,
int  ignore_consensus 
)

As circuit_build_times_disabled, but take options as an argument.

Definition at line 128 of file circuitstats.c.

Referenced by circuit_build_times_disabled().

◆ circuit_build_times_enough_to_compute()

int circuit_build_times_enough_to_compute ( const circuit_build_times_t *  cbt)

Return true iff cbt has recorded enough build times that we want to start acting on the timeout it implies.

Definition at line 259 of file circuitstats.c.

Referenced by circuit_build_times_needs_circuits(), and circuit_build_times_set_timeout_worker().

◆ circuit_build_times_free_timeouts()

void circuit_build_times_free_timeouts ( circuit_build_times_t *  cbt)

Free the saved timeouts, if the cbtdisabled consensus parameter got turned on or something.

Definition at line 595 of file circuitstats.c.

◆ circuit_build_times_handle_completed_hop()

void circuit_build_times_handle_completed_hop ( origin_circuit_t circ)

Perform the build time work that needs to be done when a circuit completes a hop.

This function decides if we should record a circuit's build time in our histogram data and other statistics, and if so, records it. It also will mark circuits that have already timed out as measurement-only circuits, so they can continue to build but not get used.

For this, we want to consider circuits that will eventually make it to the third hop. For circuits longer than 3 hops, we want to record their build time when they reach the third hop, but let them continue (and not count them later). For circuits that are exactly 3 hops, this will count them when they are completed. We do this so that CBT is always gathering statistics on circuits of the same length, regardless of their type.

Definition at line 683 of file circuitstats.c.

◆ circuit_build_times_init()

void circuit_build_times_init ( circuit_build_times_t *  cbt)

Initialize the buildtimes structure for first use.

Sets the initial timeout values based on either the config setting, the consensus param, or the default (CBT_DEFAULT_TIMEOUT_INITIAL_VALUE).

Definition at line 569 of file circuitstats.c.

Referenced by circuit_build_times_parse_state().

◆ circuit_build_times_initial_timeout()

int32_t circuit_build_times_initial_timeout ( void  )

Retrieve and bounds-check the cbtinitialtimeout consensus parameter.

Effect: This is the timeout value to use before computing a timeout, in milliseconds.

Definition at line 374 of file circuitstats.c.

◆ circuit_build_times_mark_circ_as_measurement_only()

void circuit_build_times_mark_circ_as_measurement_only ( origin_circuit_t circ)

Mark this circuit as timed out, but change its purpose so that it continues to build, allowing us to measure its full build time.

Definition at line 641 of file circuitstats.c.

◆ circuit_build_times_needs_circuits()

int circuit_build_times_needs_circuits ( const circuit_build_times_t *  cbt)

Returns true if we need circuits to be built

Definition at line 1387 of file circuitstats.c.

Referenced by circuit_build_times_needs_circuits_now().

◆ circuit_build_times_needs_circuits_now()

int circuit_build_times_needs_circuits_now ( const circuit_build_times_t *  cbt)

Returns true if we should build a timeout test circuit right now.

Definition at line 1398 of file circuitstats.c.

◆ circuit_build_times_network_check_live()

int circuit_build_times_network_check_live ( const circuit_build_times_t *  cbt)

When the network is not live, we do not record circuit build times.

The network is considered not live if there has been at least one circuit build that began and ended (had its close_ms measurement period expire) since we last received a cell.

Also has the side effect of rewinding the circuit time history in the case of recent liveness changes.

Definition at line 1595 of file circuitstats.c.

Referenced by circuit_build_times_count_close().

◆ circuit_build_times_network_circ_success()

void circuit_build_times_network_circ_success ( circuit_build_times_t *  cbt)

Called to indicate that we "completed" a circuit. Because this circuit succeeded, it doesn't count as a timeout-after-the-first-hop.

(For the purposes of the cbt code, we consider a circuit "completed" if it has 3 hops, regardless of its final hop count. We do this because we're trying to answer the question, "how long should a circuit take to reach the 3-hop count".)

This is used by circuit_build_times_network_check_changed() to determine if we had too many recent timeouts and need to reset our learned timeout to something higher.

Definition at line 1475 of file circuitstats.c.

◆ circuit_build_times_network_is_live()

void circuit_build_times_network_is_live ( circuit_build_times_t *  cbt)

Called to indicate that the network showed some signs of liveness, i.e. we received a cell.

This is used by circuit_build_times_network_check_live() to decide if we should record the circuit build timeout or not.

This function is called every time we receive a cell. Avoid syscalls, events, and other high-intensity work.

Definition at line 1421 of file circuitstats.c.

Referenced by channel_do_open_actions(), and connection_or_launch_v3_or_handshake().

◆ circuit_build_times_new_consensus_params()

void circuit_build_times_new_consensus_params ( circuit_build_times_t *  cbt,
networkstatus_t ns 
)

This function is called when we get a consensus update.

It checks to see if we have changed any consensus parameters that require reallocation or discard of previous stats.

Definition at line 430 of file circuitstats.c.

◆ circuit_build_times_parse_state()

int circuit_build_times_parse_state ( circuit_build_times_t *  cbt,
or_state_t state 
)

Load histogram from state, shuffling the resulting array after we do so. Use this result to estimate parameters and calculate the timeout.

Return -1 on error.

Definition at line 1058 of file circuitstats.c.

◆ circuit_build_times_quantile_cutoff()

double circuit_build_times_quantile_cutoff ( void  )

Retrieve and bounds-check the cbtquantile consensus parameter.

Effect: This is the position on the quantile curve to use to set the timeout value. It is a percent (10-99).

Definition at line 271 of file circuitstats.c.

Referenced by circuit_build_times_close_quantile(), and circuit_build_times_set_timeout_worker().

◆ circuit_build_times_set_timeout()

void circuit_build_times_set_timeout ( circuit_build_times_t *  cbt)

Exposed function to compute a new timeout. Dispatches events and also filters out extremely high timeout values.

Definition at line 1820 of file circuitstats.c.

◆ circuit_build_times_timeout_rate()

double circuit_build_times_timeout_rate ( const circuit_build_times_t *  cbt)

Count the number of timeouts in a set of cbt data.

Definition at line 1678 of file circuitstats.c.

Referenced by circuit_build_times_filter_timeouts().

◆ circuit_build_times_update_state()

void circuit_build_times_update_state ( const circuit_build_times_t *  cbt,
or_state_t state 
)

Output a histogram of current circuit build times to the or_state_t state structure.

Definition at line 932 of file circuitstats.c.

◆ get_circuit_build_close_time_ms()

double get_circuit_build_close_time_ms ( void  )

Return the time to wait before actually closing an under-construction, in milliseconds.

Definition at line 97 of file circuitstats.c.

◆ get_circuit_build_timeout_ms()

double get_circuit_build_timeout_ms ( void  )

Return the time to wait before giving up on an under-construction circuit, in milliseconds.

Definition at line 105 of file circuitstats.c.

Referenced by circuit_build_times_handle_completed_hop().

◆ get_circuit_build_times()

const circuit_build_times_t* get_circuit_build_times ( void  )

Return a pointer to the data structure describing our current circuit build time history and computations.

Definition at line 82 of file circuitstats.c.

◆ get_circuit_build_times_mutable()

circuit_build_times_t* get_circuit_build_times_mutable ( void  )

As get_circuit_build_times, but return a mutable pointer.

Definition at line 89 of file circuitstats.c.

Referenced by channel_do_open_actions(), and connection_or_launch_v3_or_handshake().