1 /* Copyright (c) 2001 Matej Pfajfar. 2 * Copyright (c) 2001-2004, Roger Dingledine. 3 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson. 4 * Copyright (c) 2007-2021, The Tor Project, Inc. */ 5 /* See LICENSE for licensing information */ 6 7 /** 8 * \file circuitstats.h 9 * \brief Header file for circuitstats.c 10 **/ 11 12 #ifndef TOR_CIRCUITSTATS_H 13 #define TOR_CIRCUITSTATS_H 14 15 const circuit_build_times_t *get_circuit_build_times(void); 16 circuit_build_times_t *get_circuit_build_times_mutable(void); 17 double get_circuit_build_close_time_ms(void); 18 double get_circuit_build_timeout_ms(void); 19 20 int circuit_build_times_disabled(const or_options_t *options); 21 int circuit_build_times_disabled_(const or_options_t *options, 22 int ignore_consensus); 23 24 /** A build_time_t is milliseconds */ 25 typedef uint32_t build_time_t; 26 27 int circuit_build_times_enough_to_compute(const circuit_build_times_t *cbt); 28 void circuit_build_times_update_state(const circuit_build_times_t *cbt, 29 or_state_t *state); 30 int circuit_build_times_parse_state(circuit_build_times_t *cbt, 31 or_state_t *state); 32 void circuit_build_times_count_timeout(circuit_build_times_t *cbt, 33 int did_onehop); 34 int circuit_build_times_count_close(circuit_build_times_t *cbt, 35 int did_onehop, time_t start_time); 36 void circuit_build_times_set_timeout(circuit_build_times_t *cbt); 37 int circuit_build_times_add_time(circuit_build_times_t *cbt, 38 build_time_t time); 39 int circuit_build_times_needs_circuits(const circuit_build_times_t *cbt); 40 void circuit_build_times_handle_completed_hop(origin_circuit_t *circ); 41 42 int circuit_build_times_needs_circuits_now(const circuit_build_times_t *cbt); 43 void circuit_build_times_init(circuit_build_times_t *cbt); 44 void circuit_build_times_free_timeouts(circuit_build_times_t *cbt); 45 void circuit_build_times_new_consensus_params(circuit_build_times_t *cbt, 46 const networkstatus_t *ns); 47 double circuit_build_times_timeout_rate(const circuit_build_times_t *cbt); 48 double circuit_build_times_close_rate(const circuit_build_times_t *cbt); 49 50 void circuit_build_times_update_last_circ(circuit_build_times_t *cbt); 51 void circuit_build_times_mark_circ_as_measurement_only(origin_circuit_t *circ); 52 void circuit_build_times_reset(circuit_build_times_t *cbt); 53 54 /** Total size of the circuit timeout history to accumulate. 55 * 1000 is approx 2.5 days worth of continual-use circuits. */ 56 #define CBT_NCIRCUITS_TO_OBSERVE 1000 57 58 /** Width of the histogram bins in milliseconds */ 59 #define CBT_BIN_WIDTH ((build_time_t)10) 60 61 /** Number of modes to use in the weighted-avg computation of Xm */ 62 #define CBT_DEFAULT_NUM_XM_MODES 10 63 #define CBT_MIN_NUM_XM_MODES 1 64 #define CBT_MAX_NUM_XM_MODES 20 65 66 /** 67 * CBT_BUILD_ABANDONED is our flag value to represent a force-closed 68 * circuit (Aka a 'right-censored' pareto value). 69 */ 70 #define CBT_BUILD_ABANDONED ((build_time_t)(INT32_MAX-1)) 71 #define CBT_BUILD_TIME_MAX ((build_time_t)(INT32_MAX)) 72 73 /** Save state every 10 circuits */ 74 #define CBT_SAVE_STATE_EVERY 10 75 76 /* Circuit build times consensus parameters */ 77 78 /** 79 * How long to wait before actually closing circuits that take too long to 80 * build in terms of CDF quantile. 81 */ 82 #define CBT_DEFAULT_CLOSE_QUANTILE 99 83 #define CBT_MIN_CLOSE_QUANTILE CBT_MIN_QUANTILE_CUTOFF 84 #define CBT_MAX_CLOSE_QUANTILE CBT_MAX_QUANTILE_CUTOFF 85 86 /** 87 * How many circuits count as recent when considering if the 88 * connection has gone gimpy or changed. 89 */ 90 #define CBT_DEFAULT_RECENT_CIRCUITS 20 91 #define CBT_MIN_RECENT_CIRCUITS 3 92 #define CBT_MAX_RECENT_CIRCUITS 1000 93 94 /** 95 * Maximum count of timeouts that finish the first hop in the past 96 * RECENT_CIRCUITS before calculating a new timeout. 97 * 98 * This tells us whether to abandon timeout history and set 99 * the timeout back to whatever circuit_build_times_get_initial_timeout() 100 * gives us. 101 */ 102 #define CBT_DEFAULT_MAX_RECENT_TIMEOUT_COUNT (CBT_DEFAULT_RECENT_CIRCUITS*9/10) 103 #define CBT_MIN_MAX_RECENT_TIMEOUT_COUNT 3 104 #define CBT_MAX_MAX_RECENT_TIMEOUT_COUNT 10000 105 106 /** Minimum circuits before estimating a timeout */ 107 #define CBT_DEFAULT_MIN_CIRCUITS_TO_OBSERVE 100 108 #define CBT_MIN_MIN_CIRCUITS_TO_OBSERVE 1 109 #define CBT_MAX_MIN_CIRCUITS_TO_OBSERVE 10000 110 111 /** Cutoff percentile on the CDF for our timeout estimation. */ 112 #define CBT_DEFAULT_QUANTILE_CUTOFF 80 113 #define CBT_MIN_QUANTILE_CUTOFF 10 114 #define CBT_MAX_QUANTILE_CUTOFF 99 115 double circuit_build_times_quantile_cutoff(void); 116 117 /** How often in seconds should we build a test circuit */ 118 #define CBT_DEFAULT_TEST_FREQUENCY 10 119 #define CBT_MIN_TEST_FREQUENCY 1 120 #define CBT_MAX_TEST_FREQUENCY INT32_MAX 121 122 /** Lowest allowable value for CircuitBuildTimeout in milliseconds */ 123 #define CBT_DEFAULT_TIMEOUT_MIN_VALUE (CBT_BIN_WIDTH) 124 #define CBT_MIN_TIMEOUT_MIN_VALUE CBT_BIN_WIDTH 125 #define CBT_MAX_TIMEOUT_MIN_VALUE INT32_MAX 126 127 /** Initial circuit build timeout in milliseconds */ 128 #define CBT_DEFAULT_TIMEOUT_INITIAL_VALUE (60*1000) 129 #define CBT_MIN_TIMEOUT_INITIAL_VALUE CBT_MIN_TIMEOUT_MIN_VALUE 130 #define CBT_MAX_TIMEOUT_INITIAL_VALUE INT32_MAX 131 int32_t circuit_build_times_initial_timeout(void); 132 133 #if CBT_DEFAULT_MAX_RECENT_TIMEOUT_COUNT < CBT_MIN_MAX_RECENT_TIMEOUT_COUNT 134 #error "RECENT_CIRCUITS is set too low." 135 #endif 136 137 #ifdef CIRCUITSTATS_PRIVATE 138 STATIC double circuit_build_times_calculate_timeout(circuit_build_times_t *cbt, 139 double quantile); 140 STATIC int circuit_build_times_update_alpha(circuit_build_times_t *cbt); 141 142 /* Network liveness functions */ 143 STATIC int circuit_build_times_network_check_changed( 144 circuit_build_times_t *cbt); 145 STATIC build_time_t circuit_build_times_get_xm(circuit_build_times_t *cbt); 146 #endif /* defined(CIRCUITSTATS_PRIVATE) */ 147 148 #ifdef TOR_UNIT_TESTS 149 build_time_t circuit_build_times_generate_sample(circuit_build_times_t *cbt, 150 double q_lo, double q_hi); 151 double circuit_build_times_cdf(circuit_build_times_t *cbt, double x); 152 void circuit_build_times_initial_alpha(circuit_build_times_t *cbt, 153 double quantile, double time_ms); 154 void circuitbuild_running_unit_tests(void); 155 #endif /* defined(TOR_UNIT_TESTS) */ 156 157 /* Network liveness functions */ 158 void circuit_build_times_network_is_live(circuit_build_times_t *cbt); 159 int circuit_build_times_network_check_live(const circuit_build_times_t *cbt); 160 void circuit_build_times_network_circ_success(circuit_build_times_t *cbt); 161 162 /** Information about the state of our local network connection */ 163 typedef struct { 164 /** The timestamp we last completed a TLS handshake or received a cell */ 165 time_t network_last_live; 166 /** If the network is not live, how many timeouts has this caused? */ 167 int nonlive_timeouts; 168 /** Circular array of circuits that have made it to the first hop. Slot is 169 * 1 if circuit timed out, 0 if circuit succeeded */ 170 int8_t *timeouts_after_firsthop; 171 /** Number of elements allocated for the above array */ 172 int num_recent_circs; 173 /** Index into circular array. */ 174 int after_firsthop_idx; 175 } network_liveness_t; 176 177 /** Structure for circuit build times history */ 178 struct circuit_build_times_t { 179 /** The circular array of recorded build times in milliseconds */ 180 build_time_t circuit_build_times[CBT_NCIRCUITS_TO_OBSERVE]; 181 /** Current index in the circuit_build_times circular array */ 182 int build_times_idx; 183 /** Total number of build times accumulated. Max CBT_NCIRCUITS_TO_OBSERVE */ 184 int total_build_times; 185 /** Information about the state of our local network connection */ 186 network_liveness_t liveness; 187 /** Last time we built a circuit. Used to decide to build new test circs */ 188 time_t last_circ_at; 189 /** "Minimum" value of our pareto distribution (actually mode) */ 190 build_time_t Xm; 191 /** alpha exponent for pareto dist. */ 192 double alpha; 193 /** Have we computed a timeout? */ 194 int have_computed_timeout; 195 /** The exact value for that timeout in milliseconds. Stored as a double 196 * to maintain precision from calculations to and from quantile value. */ 197 double timeout_ms; 198 /** How long we wait before actually closing the circuit. */ 199 double close_ms; 200 /** Total succeeded counts. Old measurements may be scaled downward if 201 * we've seen a lot of circuits. */ 202 uint32_t num_circ_succeeded; 203 /** Total timeout counts. Old measurements may be scaled downward if 204 * we've seen a lot of circuits. */ 205 uint32_t num_circ_timeouts; 206 /** Total closed counts. Old measurements may be scaled downward if 207 * we've seen a lot of circuits.*/ 208 uint32_t num_circ_closed; 209 210 }; 211 212 #endif /* !defined(TOR_CIRCUITSTATS_H) */ 213