| 1 | package telemetry |
| 2 | |
| 3 | import "time" |
| 4 | |
| 5 | // SelectionTrace records observability data for a single relay-selection |
| 6 | // invocation. |
| 7 | type SelectionTrace struct { |
| 8 | Timestamp time.Time |
| 9 | |
| 10 | // ClientHash is hashToGF64(LocalAddress) — a single byte derived from the |
| 11 | // client identity. Used only for sampled debug-log correlation. Not a |
| 12 | // Prometheus label (would unbounded cardinality) and not a public field on |
| 13 | // any external API. |
| 14 | ClientHash uint8 |
| 15 | |
| 16 | // Mode is "priority" or "multihop", matching the calling method. |
| 17 | Mode string |
| 18 | |
| 19 | // Pool snapshot at selection time. |
| 20 | PoolTotal int |
| 21 | PoolEligible int |
| 22 | PoolFallback int |
| 23 | |
| 24 | // Suppressed lists URLs excluded from selection along with the reason map. |
| 25 | Suppressed []string |
| 26 | Reasons map[string]string |
| 27 | |
| 28 | // Congested is true when the existing congestion-grid switch is active |
| 29 | // (RTT mean > molsCongestionRTTThreshold). |
| 30 | Congested bool |
| 31 | |
| 32 | // NonLinear is true when the variant-grid multiplier flip is active |
| 33 | // (CV > molsCVThreshold). |
| 34 | NonLinear bool |
| 35 | |
| 36 | // M1, M2 are the MOLS multipliers used for this selection. |
| 37 | M1, M2 uint8 |
| 38 | |
| 39 | // AvgRTT is the mean discovery RTT across the auto pool sample. |
| 40 | AvgRTT time.Duration |
| 41 | |
| 42 | // CV is the coefficient of variation of per-relay discovery RTTs. |
| 43 | CV float64 |
| 44 | |
| 45 | // Ranked carries per-relay scoring detail for every candidate considered |
| 46 | // (excluded URLs appear in Suppressed/Reasons instead). |
| 47 | Ranked []TraceEntry |
| 48 | |
| 49 | // OutputURLs is the final ordered list returned by the selection method. |
| 50 | OutputURLs []string |
| 51 | |
| 52 | // SelectionTook is wall time spent in the selection method. |
| 53 | SelectionTook time.Duration |
| 54 | } |
| 55 | |
| 56 | // TraceEntry captures per-relay scoring detail within a SelectionTrace. |
| 57 | type TraceEntry struct { |
| 58 | URL string |
| 59 | Score int |
| 60 | Confirmed bool |
| 61 | RTT time.Duration |
| 62 | Demoted bool |
| 63 | } |