Files
horizon-airdef/crates/horizon-telemetry/src/lib.rs
T
Ludovic Marie 828398b5ec Telemetry: every hardware fact that explains performance, broken down by class
What players send (opt-in, unchanged switches) now describes the whole machine:
CPU cores and base/boost clock, the GPU's maker, integrated or discrete and its
VRAM, the drive under the game folder (NVMe/SSD/HDD), the screen (size, refresh,
scale), on battery or mains, laptop or desktop. Perf, crash and bug items carry
them in `system`; benchmark reports in `hardware`. No serials, host or user
names, or paths. CONSENT_VERSION goes to 2, so players are asked again.

The server keeps the new fields in `systems.extra` (the table is rebuilt once
on old databases, ids kept). /v1/aggregate and /v1/benchmarks/summary add
breakdowns by RAM class, VRAM class, drive, OS and integrated/discrete GPU;
a class is published only with at least 3 different installs, never a raw value.
website/scripts/benchmarks.mjs mirrors the classes on the shared fixtures.

The summary's "not Horizon or plain vanilla" check returned None (accepted)
instead of the rejection; it now matches the site's script.

The launcher's "View what would be sent" and `data show` list every field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 01:59:39 +02:00

126 lines
4.6 KiB
Rust

//! Opt-in data collection, shared by the launcher, the game and the ingest server.
//!
//! Nothing is collected or sent until the player says yes, kind by kind ([`Consent`]): the
//! game and the launcher only [`outbox::push`] items whose kind is allowed, and the launcher's
//! [`upload::flush`] drops anything the player has since turned off before it opens a
//! connection. Items are small summaries (percentiles and histogram buckets, never raw streams),
//! dated to the day, with no account, world, server or address in them ([`scrub`]); they leave
//! in zstd batches ([`batch`]). `docs/telemetry.md` lists every field.
//!
//! The one exception is [`live`]: the anonymous "I'm playing" ping the game sends while it
//! runs, for the live player count. It holds no install ID and nothing about the player.
use std::path::{Path, PathBuf};
use std::time::{SystemTime, UNIX_EPOCH};
pub mod batch;
pub mod consent;
pub mod live;
pub mod outbox;
pub mod payload;
pub mod scrub;
pub mod system;
#[cfg(feature = "upload")]
pub mod upload;
pub use consent::{Choices, Consent};
pub use payload::{Item, Kind, Payload, Source};
/// The payload format. New optional fields keep it; a field that changes meaning or goes
/// bumps it, and the server keeps reading the older ones.
pub const SCHEMA: u32 = 1;
/// What players agree to. Bumped when what is collected changes: the launcher then asks again,
/// and until the player answers nothing new is kept or sent. 2: the machine's full hardware
/// (cores, clocks, VRAM, drive, screen, power, form), 2026-10-23.
pub const CONSENT_VERSION: u32 = 2;
/// The ingest server (`crates/horizon-telemetry-server`, on Railway). `HORIZON_TELEMETRY_URL`
/// overrides it (a local server); `HORIZON_TELEMETRY_URL=off` sends nothing at all, no ping
/// either (tests and automated runs). What is sent still depends on the player's switches.
pub const DEFAULT_ENDPOINT: &str = "https://telemetry.playhorizon.dev";
/// Where items are sent, if anywhere.
pub fn endpoint() -> Option<String> {
resolve(std::env::var("HORIZON_TELEMETRY_URL").ok().as_deref())
}
fn resolve(var: Option<&str>) -> Option<String> {
match var.map(str::trim) {
Some("off" | "none" | "0") => None,
Some(url) if !url.is_empty() => Some(url.trim_end_matches('/').to_owned()),
_ => Some(DEFAULT_ENDPOINT.to_owned()),
}
}
/// `telemetry/` in the game folder: the consent, the outbox and the upload state, read by the
/// launcher and the game alike.
pub fn dir(home: &Path) -> PathBuf {
home.join("telemetry")
}
/// Days since 1970-01-01 (UTC): the only time an item carries.
pub fn today() -> u32 {
(now_secs() / 86_400) as u32
}
pub(crate) fn now_secs() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_or(0, |d| d.as_secs())
}
/// `bytes` random bytes in lowercase hex.
pub(crate) fn random_hex(bytes: usize) -> String {
let mut buf = vec![0u8; bytes];
// Without the OS's randomness the time still makes names that don't collide in practice.
if getrandom::fill(&mut buf).is_err() {
let nanos = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_or(0, |d| d.as_nanos());
for (i, b) in buf.iter_mut().enumerate() {
*b = (nanos >> (8 * (i % 16))) as u8;
}
}
buf.iter().map(|b| format!("{b:02x}")).collect()
}
/// Writes `bytes` through a temporary file, so a reader never sees half of it.
pub(crate) fn write_atomic(path: &Path, bytes: &[u8]) -> std::io::Result<()> {
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent)?;
}
let tmp = path.with_extension(format!("tmp-{}", random_hex(4)));
std::fs::write(&tmp, bytes)?;
std::fs::rename(&tmp, path)
}
#[cfg(test)]
pub(crate) mod test_home {
use std::path::PathBuf;
/// An empty folder of its own under the system's temporary folder.
pub fn new(name: &str) -> PathBuf {
let dir =
std::env::temp_dir().join(format!("horizon-telemetry-{name}-{}", super::random_hex(6)));
std::fs::create_dir_all(&dir).unwrap();
dir
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_endpoint_defaults_to_the_server_and_can_be_moved_or_turned_off() {
assert_eq!(resolve(None).as_deref(), Some(DEFAULT_ENDPOINT));
assert_eq!(resolve(Some(" ")).as_deref(), Some(DEFAULT_ENDPOINT));
assert_eq!(
resolve(Some("http://127.0.0.1:8080/")).as_deref(),
Some("http://127.0.0.1:8080")
);
assert_eq!(resolve(Some("off")), None);
assert!(DEFAULT_ENDPOINT.starts_with("https://") && !DEFAULT_ENDPOINT.ends_with('/'));
}
}