Give each install an anonymous identity

Events could not become people. Nothing identified an install — no distinct_id,
no device id, nothing persisted — so 400 pushes could have been 4 users or 40,
and retention and funnels were unanswerable. This is the question
quiltsync-telemetry-host closed on as "blocked on whether one may be attached
at all"; the answer is that counting installs needs nothing about a user.

A random UUID, minted on first run and persisted beside the app's own data,
derived from nothing. Not an email hash: that is reversible for a customer set
already known, so it would carry the obligations of personal data while feeling
as though it did not — and it counts accounts, not installs, being absent
before the first login, which is exactly where the onboarding funnel starts.

Reaches all three sinks so they can be read together: the analytics
distinct_id, the crash reporter's user.id, and a field in the diagnostic
export. A crash now leads to that install's event stream leads to the archive
its user emailed in.

Two design points worth keeping:

- The identity rides the crash client's *event hook*, beside the host tag, not
  a scope. It is fixed for the process, so this is not about staleness — a
  scope carrying it would still reach only threads that snapshotted after it
  was set. One mechanism, both facts.
- `wire_payload` is separate from `event_payload` so the two stay honest about
  whose fact each property is: the payload belongs to the *event* and is pinned
  by its own tests, while distinct_id belongs to the *install* and to nothing
  the vocabulary describes. A payloadless event still gets a properties object,
  because it still has an identity — and app launch, the head of every funnel,
  is exactly that case.

Failure semantics, which are the whole reason this is not three lines:

- Cannot persist -> report no identity, never an unpersisted one. An id that is
  not on disk is a *new* id next launch, inflating the install count precisely
  when disks are unhappy.
- Read fails for any reason other than absence -> report none, and do not mint
  a replacement, which would discard a real install's history to satisfy one run.
- Written atomically (temp + rename), so an interrupted write cannot leave a
  truncated value that reads as a different install forever.
- No identity means an *unattributed* event, never a dropped one — anything
  else loses the events of the machines having trouble.

Locally verifiable via the dry run, which shows the identity — the first unit
the rig from #820 actually pays for.

just lint 0, cargo fmt --check 0, 300 quilt-sync tests, workspace green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: fiskus

Cargo.lock

@@ -43,6 +43,7 @@ thiserror.workspace = true
 tokio.workspace = true
 tokio-stream.workspace = true
 tracing.workspace = true
+uuid.workspace = true
 tracing-appender = "0.2.5"
 tracing-subscriber = { workspace = true, features = ["env-filter"] }
 url.workspace = true

quilt-sync/src-tauri/Cargo.toml

@@ -198,8 +198,9 @@ async fn collect_diagnostic_logs_command(
     app_handle: &tauri::AppHandle,
     m: &model::Model,
     app: &app::App,
+    tracing: &crate::telemetry::Telemetry,
 ) -> Result<PathBuf, Error> {
-    let info = diagnostics::collect(app_handle, m, app).await?;
+    let info = diagnostics::collect(app_handle, m, app, tracing.install_id()).await?;
     tokio::task::spawn_blocking(move || diagnostics::save_diagnostic_zip(&info))
         .await
         .map_err(|e| e.to_string())?
@@ -216,7 +217,7 @@ pub async fn collect_diagnostic_logs(
     let app_handle = app_handle.lock().await;
     let app: &app::App = &app;
 
-    match collect_diagnostic_logs_command(&app_handle, &m, app).await {
+    match collect_diagnostic_logs_command(&app_handle, &m, app, &tracing).await {
         Ok(zip_path) => Ok(zip_path.display().to_string()),
         Err(err) => Err(err.to_string()),
     }

quilt-sync/src-tauri/src/commands/system.rs

@@ -64,8 +64,21 @@ fn main() {
         .plugin(tauri_plugin_updater::Builder::new().build())
         .setup(|app| {
             let package_info = app.package_info();
+
+            // Resolved before the sinks are built: the crash client's event hook
+            // captures the identity when the client is constructed, so it has to
+            // be known first or crashes would go out unattributed.
+            let data_dir = app
+                .path()
+                .app_local_data_dir()
+                .expect("Failed to resolve data dir");
+
             let sinks = telemetry::Sinks::resolve();
-            let telemetry = telemetry::Telemetry::new(&package_info.version, sinks);
+            let telemetry = telemetry::Telemetry::new(
+                &package_info.version,
+                sinks,
+                telemetry::install_id::load(&data_dir),
+            );
 
             // This is for runtime registering
             #[cfg(desktop)]
@@ -75,11 +88,6 @@ fn main() {
                 }
             }
 
-            let data_dir = app
-                .path()
-                .app_local_data_dir()
-                .expect("Failed to resolve data dir");
-
             let logs_dir = telemetry::Telemetry::init_file_logging(&data_dir)?;
 
             telemetry.init();

quilt-sync/src-tauri/src/main.rs

@@ -8,11 +8,13 @@ use crate::Result;
 
 pub mod diagnostics;
 pub mod event;
+pub mod install_id;
 pub mod mixpanel;
 pub mod sentry;
 pub mod tracing;
 
 pub use event::MixpanelEvent;
+pub use install_id::InstallId;
 pub use mixpanel::Analytics;
 pub use tracing::LogsDir;
 
@@ -75,10 +77,14 @@ pub struct Telemetry {
     analytics: Analytics,
     /// The host every outgoing crash report is tagged with; see [`AmbientHost`].
     host: AmbientHost,
+    /// This install's identity, on every analytics event and every crash report
+    /// so the two can be read together. `None` when it could not be persisted —
+    /// see [`install_id::load`].
+    install_id: Option<InstallId>,
 }
 
 impl Telemetry {
-    pub fn new(version: &Version, sinks: Sinks) -> Self {
+    pub fn new(version: &Version, sinks: Sinks, install_id: Option<InstallId>) -> Self {
         // The cell outlives the client and is read by its event hook, so it has
         // to exist before the client is built.
         let host: AmbientHost = Arc::new(Mutex::new(None));
@@ -87,13 +93,20 @@ impl Telemetry {
             analytics: Analytics::resolve(sinks),
             _sentry: sinks
                 .reports_crashes()
-                .then(|| sentry::sentry_config(version, Arc::clone(&host)))
+                .then(|| sentry::sentry_config(version, install_id.clone(), Arc::clone(&host)))
                 .flatten()
                 .map(::sentry::init),
             host,
+            install_id,
         }
     }
 
+    /// This install's identity, for the diagnostic export — so a report a user
+    /// emails in can be lined up against that install's event stream.
+    pub fn install_id(&self) -> Option<&InstallId> {
+        self.install_id.as_ref()
+    }
+
     pub fn init_file_logging(base_path: &std::path::Path) -> Result<LogsDir> {
         tracing::init_file_logging(base_path)
     }
@@ -119,7 +132,9 @@ impl Telemetry {
         if let Some(host) = event.host() {
             self.add_host(host);
         }
-        if let Err(err) = mixpanel::track_event(&self.analytics, &event).await {
+        if let Err(err) =
+            mixpanel::track_event(&self.analytics, &event, self.install_id.as_ref()).await
+        {
             Sentry::capture_error(&err);
         }
     }
@@ -145,7 +160,7 @@ impl Telemetry {
     }
 
     pub fn init(&self) {
-        mixpanel::init(&self.analytics);
+        mixpanel::init(&self.analytics, self.install_id.clone());
     }
 
     /// Returns the current global maximum log level as a human-readable string.
@@ -165,6 +180,7 @@ impl Default for Telemetry {
             _sentry: None,
             analytics: Analytics::Off,
             host: Arc::new(Mutex::new(None)),
+            install_id: None,
         }
     }
 }
@@ -201,7 +217,7 @@ mod tests {
             std::env::set_var("SENTRY_DSN", "https://public@example.invalid/1");
         }
 
-        let telemetry = Telemetry::new(&Version::new(0, 0, 0), Sinks::resolve());
+        let telemetry = Telemetry::new(&Version::new(0, 0, 0), Sinks::resolve(), None);
         assert!(
             matches!(telemetry.analytics, Analytics::DryRun),
             "a local build must never construct a live analytics client"

quilt-sync/src-tauri/src/telemetry.rs

@@ -20,6 +20,9 @@ pub struct DiagnosticInfo {
     pub home_dir: String,
     pub logs_dir: PathBuf,
     pub auth_hosts: Vec<String>,
+    /// This install's identity, so a report a user emails in can be lined up
+    /// against that install's event stream and its crash reports.
+    pub install_id: Option<String>,
 }
 
 /// Typed shape of `metadata.json` stored inside a diagnostic zip.
@@ -30,6 +33,10 @@ struct DiagnosticMetadata {
     data_dir: String,
     home_dir: String,
     authenticated_hosts: Vec<String>,
+    /// Absent on an install whose identity could not be persisted, so a missing
+    /// value here means "no identity", never "an older export".
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    install_id: Option<String>,
 }
 
 impl DiagnosticMetadata {
@@ -40,6 +47,7 @@ impl DiagnosticMetadata {
             data_dir: info.data_dir.display().to_string(),
             home_dir: info.home_dir.clone(),
             authenticated_hosts: info.auth_hosts.clone(),
+            install_id: info.install_id.clone(),
         }
     }
 }
@@ -49,6 +57,7 @@ pub async fn collect(
     app_handle: &tauri::AppHandle,
     m: &Model,
     app: &App,
+    install_id: Option<&crate::telemetry::InstallId>,
 ) -> Result<DiagnosticInfo, Error> {
     let local_data_dir = app_handle.path().app_local_data_dir()?;
     let auth_hosts = quilt::paths::list_auth_hosts(&local_data_dir);
@@ -70,6 +79,7 @@ pub async fn collect(
         home_dir,
         logs_dir: app.logs_dir.path().to_path_buf(),
         auth_hosts,
+        install_id: install_id.map(|id| id.as_str().to_string()),
     })
 }
 
@@ -98,6 +108,9 @@ pub fn send_crash_report(zip_path: &Path) -> Result<(), Error> {
                 scope.set_extra("os", m.os.clone().into());
                 scope.set_extra("data_dir", m.data_dir.clone().into());
                 scope.set_extra("home_dir", m.home_dir.clone().into());
+                if let Some(ref install_id) = m.install_id {
+                    scope.set_extra("install_id", install_id.clone().into());
+                }
                 scope.set_extra(
                     "authenticated_hosts",
                     serde_json::json!(m.authenticated_hosts),
@@ -223,6 +236,7 @@ mod tests {
             home_dir: "/home/tester".to_string(),
             logs_dir,
             auth_hosts,
+            install_id: Some("test-install-id".to_string()),
         }
     }