src/core/or/circuitstats.h

   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-2019, 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                                               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
  53 /** Total size of the circuit timeout history to accumulate.
  54  * 1000 is approx 2.5 days worth of continual-use circuits. */
  55 #define CBT_NCIRCUITS_TO_OBSERVE 1000
  56
  57 /** Width of the histogram bins in milliseconds */
  58 #define CBT_BIN_WIDTH ((build_time_t)10)
  59
  60 /** Number of modes to use in the weighted-avg computation of Xm */
  61 #define CBT_DEFAULT_NUM_XM_MODES 10
  62 #define CBT_MIN_NUM_XM_MODES 1
  63 #define CBT_MAX_NUM_XM_MODES 20
  64
  65 /**
  66  * CBT_BUILD_ABANDONED is our flag value to represent a force-closed
  67  * circuit (Aka a 'right-censored' pareto value).
  68  */
  69 #define CBT_BUILD_ABANDONED ((build_time_t)(INT32_MAX-1))
  70 #define CBT_BUILD_TIME_MAX ((build_time_t)(INT32_MAX))
  71
  72 /** Save state every 10 circuits */
  73 #define CBT_SAVE_STATE_EVERY 10
  74
  75 /* Circuit build times consensus parameters */
  76
  77 /**
  78  * How long to wait before actually closing circuits that take too long to
  79  * build in terms of CDF quantile.
  80  */
  81 #define CBT_DEFAULT_CLOSE_QUANTILE 99
  82 #define CBT_MIN_CLOSE_QUANTILE CBT_MIN_QUANTILE_CUTOFF
  83 #define CBT_MAX_CLOSE_QUANTILE CBT_MAX_QUANTILE_CUTOFF
  84
  85 /**
  86  * How many circuits count as recent when considering if the
  87  * connection has gone gimpy or changed.
  88  */
  89 #define CBT_DEFAULT_RECENT_CIRCUITS 20
  90 #define CBT_MIN_RECENT_CIRCUITS 3
  91 #define CBT_MAX_RECENT_CIRCUITS 1000
  92
  93 /**
  94  * Maximum count of timeouts that finish the first hop in the past
  95  * RECENT_CIRCUITS before calculating a new timeout.
  96  *
  97  * This tells us whether to abandon timeout history and set
  98  * the timeout back to whatever circuit_build_times_get_initial_timeout()
  99  * gives us.
 100  */
 101 #define CBT_DEFAULT_MAX_RECENT_TIMEOUT_COUNT (CBT_DEFAULT_RECENT_CIRCUITS*9/10)
 102 #define CBT_MIN_MAX_RECENT_TIMEOUT_COUNT 3
 103 #define CBT_MAX_MAX_RECENT_TIMEOUT_COUNT 10000
 104
 105 /** Minimum circuits before estimating a timeout */
 106 #define CBT_DEFAULT_MIN_CIRCUITS_TO_OBSERVE 100
 107 #define CBT_MIN_MIN_CIRCUITS_TO_OBSERVE 1
 108 #define CBT_MAX_MIN_CIRCUITS_TO_OBSERVE 10000
 109
 110 /** Cutoff percentile on the CDF for our timeout estimation. */
 111 #define CBT_DEFAULT_QUANTILE_CUTOFF 80
 112 #define CBT_MIN_QUANTILE_CUTOFF 10
 113 #define CBT_MAX_QUANTILE_CUTOFF 99
 114 double circuit_build_times_quantile_cutoff(void);
 115
 116 /** How often in seconds should we build a test circuit */
 117 #define CBT_DEFAULT_TEST_FREQUENCY 10
 118 #define CBT_MIN_TEST_FREQUENCY 1
 119 #define CBT_MAX_TEST_FREQUENCY INT32_MAX
 120
 121 /** Lowest allowable value for CircuitBuildTimeout in milliseconds */
 122 #define CBT_DEFAULT_TIMEOUT_MIN_VALUE (CBT_BIN_WIDTH)
 123 #define CBT_MIN_TIMEOUT_MIN_VALUE CBT_BIN_WIDTH
 124 #define CBT_MAX_TIMEOUT_MIN_VALUE INT32_MAX
 125
 126 /** Initial circuit build timeout in milliseconds */
 127 #define CBT_DEFAULT_TIMEOUT_INITIAL_VALUE (60*1000)
 128 #define CBT_MIN_TIMEOUT_INITIAL_VALUE CBT_MIN_TIMEOUT_MIN_VALUE
 129 #define CBT_MAX_TIMEOUT_INITIAL_VALUE INT32_MAX
 130 int32_t circuit_build_times_initial_timeout(void);
 131
 132 #if CBT_DEFAULT_MAX_RECENT_TIMEOUT_COUNT < CBT_MIN_MAX_RECENT_TIMEOUT_COUNT
 133 #error "RECENT_CIRCUITS is set too low."
 134 #endif
 135
 136 #ifdef CIRCUITSTATS_PRIVATE
 137 STATIC double circuit_build_times_calculate_timeout(circuit_build_times_t *cbt,
 138                                              double quantile);
 139 STATIC int circuit_build_times_update_alpha(circuit_build_times_t *cbt);
 140 STATIC void circuit_build_times_reset(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 #endif /* defined(CIRCUITSTATS_PRIVATE) */
 146
 147 #ifdef TOR_UNIT_TESTS
 148 build_time_t circuit_build_times_generate_sample(circuit_build_times_t *cbt,
 149                                                  double q_lo, double q_hi);
 150 double circuit_build_times_cdf(circuit_build_times_t *cbt, double x);
 151 void circuit_build_times_initial_alpha(circuit_build_times_t *cbt,
 152                                        double quantile, double time_ms);
 153 void circuitbuild_running_unit_tests(void);
 154 #endif /* defined(TOR_UNIT_TESTS) */
 155
 156 /* Network liveness functions */
 157 void circuit_build_times_network_is_live(circuit_build_times_t *cbt);
 158 int circuit_build_times_network_check_live(const circuit_build_times_t *cbt);
 159 void circuit_build_times_network_circ_success(circuit_build_times_t *cbt);
 160
 161 #ifdef CIRCUITSTATS_PRIVATE
 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_s {
 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 #endif /* defined(CIRCUITSTATS_PRIVATE) */
 212
 213 #endif /* !defined(TOR_CIRCUITSTATS_H) */