chore: restore machine_id in telemetry

Re-add the persistent machine_id field that was removed in the previous
commit. A per-installation UUID is standard practice for CLI telemetry
(Next.js, .NET CLI, AWS CDK all do this) and enables cross-batch
analysis like version upgrade tracking and unique installation counts.

The batch/sequence documentation additions from the previous commit are
preserved.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: lwshang

crates/icp-cli/src/telemetry.rs

@@ -20,6 +20,7 @@ use time::OffsetDateTime;
 use crate::version::icp_cli_version_str;
 
 const EVENTS_FILE: &str = "events.jsonl";
+const MACHINE_ID_FILE: &str = "machine-id";
 const NOTICE_SHOWN_FILE: &str = "notice-shown";
 const NEXT_SEND_TIME_FILE: &str = "next-send-time";
 
@@ -71,6 +72,7 @@ pub(crate) struct Argument {
 #[derive(Debug, Serialize, Deserialize)]
 pub(crate) struct TelemetryRecord {
     // --- Metadata that is constant across all events on the same machine
+    pub machine_id: String,
     pub platform: String,
     pub arch: &'static str,
 
@@ -130,11 +132,13 @@ impl TelemetrySession {
 
     /// Finish the session, record the event, and trigger a send if needed.
     pub(crate) fn finish(self, success: bool, telemetry_data: &TelemetryData) {
+        let machine_id = get_or_create_machine_id(&self.telemetry_dir);
         let duration_ms = self.start.elapsed().as_millis() as u64;
 
         let date = OffsetDateTime::now_utc().date().to_string();
 
         let record = TelemetryRecord {
+            machine_id,
             platform: if cfg!(target_os = "linux") && std::env::var_os("WSL_DISTRO_NAME").is_some()
             {
                 "wsl".to_string()
@@ -233,6 +237,20 @@ fn show_notice_if_needed(telemetry_dir: &Path) {
     let _ = std::fs::write(&marker, "");
 }
 
+fn get_or_create_machine_id(telemetry_dir: &Path) -> String {
+    let path = telemetry_dir.join(MACHINE_ID_FILE);
+    if let Ok(id) = std::fs::read_to_string(&path) {
+        let id = id.trim().to_string();
+        if !id.is_empty() {
+            return id;
+        }
+    }
+    let id = uuid::Uuid::new_v4().to_string();
+    let _ = std::fs::create_dir_all(telemetry_dir);
+    let _ = std::fs::write(&path, &id);
+    id
+}
+
 fn append_record(telemetry_dir: &Path, record: &TelemetryRecord) {
     let Ok(line) = serde_json::to_string(record) else {
         return;

crates/icp-cli/tests/telemetry_tests.rs

@@ -10,6 +10,7 @@
 //! 5. **No rotation when triggers not met** — events.jsonl kept intact
 //! 6. **Batch send** — `__telemetry-send-batch`: payload shape, silent failure, file cleanup
 //! 7. **Stale batch cleanup** — old/excess batch files pruned when a send is triggered
+//! 8. **Machine-id persistence** — same UUID is reused across invocations
 //!
 //! Full-pipeline tests run `icp settings telemetry` (a fast, network-free
 //! command) with `ICP_HOME` set to a known temp path and all opt-out env vars
@@ -28,7 +29,7 @@ mod common;
 use common::TestContext;
 
 /// A minimal, syntactically-valid NDJSON telemetry record.
-const FAKE_RECORD: &str = r#"{"platform":"test","arch":"x86_64","version":"0.0.0","command":"version","arguments":[],"success":true,"duration_ms":42}"#;
+const FAKE_RECORD: &str = r#"{"machine_id":"test-machine","platform":"test","arch":"x86_64","version":"0.0.0","command":"version","arguments":[],"success":true,"duration_ms":42}"#;
 
 /// A timestamp guaranteed to be far in the future (~year 2286).
 /// Written to `next-send-time` to prevent the time-based send trigger from
@@ -174,6 +175,13 @@ fn telemetry_record_appended_to_events_file() {
     let record: Value = serde_json::from_str(first_line).expect("record must be valid JSON");
 
     // Required fields
+    assert!(
+        record["machine_id"]
+            .as_str()
+            .map(|s| !s.is_empty())
+            .unwrap_or(false),
+        "machine_id must be a non-empty string"
+    );
     assert!(
         !record["platform"].as_str().unwrap_or("").is_empty(),
         "platform must be present"
@@ -373,6 +381,7 @@ fn telemetry_send_batch_delivers_data() {
             request::body(matches("\"batch\"")),
             request::body(matches("\"sequence\"")),
             // Original fields must be preserved.
+            request::body(matches("\"machine_id\":\"test-machine\"")),
             request::body(matches("\"command\":\"version\"")),
         ])
         .times(1)
@@ -471,3 +480,46 @@ fn telemetry_excess_batches_pruned_on_trigger() {
         "batch count must be pruned to ≤10; found {remaining}"
     );
 }
+
+/// The same `machine_id` UUID must appear in all records produced by
+/// consecutive command invocations.
+#[test]
+fn telemetry_machine_id_persists_across_invocations() {
+    let ctx = TestContext::new();
+    let icp_home = ctx.home_path().join("icp-home");
+    let telemetry_dir = icp_home.join("telemetry");
+
+    // Keep next-send-time in the future so events.jsonl is never rotated
+    // and both records land in the same file.
+    init_telemetry_dir(&telemetry_dir, Some(FAR_FUTURE_SECS));
+
+    for _ in 0..2 {
+        ctx.icp()
+            .env("ICP_HOME", icp_home.as_str())
+            .env_remove("CI")
+            .env_remove("DO_NOT_TRACK")
+            .env_remove("ICP_TELEMETRY_DISABLED")
+            .args(["settings", "telemetry"])
+            .assert()
+            .success();
+    }
+
+    let contents = std::fs::read_to_string(telemetry_dir.join("events.jsonl")).unwrap();
+    let ids: Vec<&str> = contents
+        .lines()
+        .filter_map(|l| serde_json::from_str::<Value>(l).ok())
+        .filter_map(|v| {
+            v["machine_id"]
+                .as_str()
+                .map(str::to_owned)
+                .map(|s| Box::leak(s.into_boxed_str()) as &str)
+        })
+        .collect();
+
+    assert_eq!(ids.len(), 2, "expected 2 records");
+    assert_eq!(
+        ids[0], ids[1],
+        "machine_id must be identical across invocations: got {:?} and {:?}",
+        ids[0], ids[1]
+    );
+}

docs/telemetry.md

@@ -10,6 +10,7 @@ Each command invocation produces a single telemetry record with the following fi
 |---|---|---|
 | `batch` | `a1b2c3d4-...` | Group records from the same transmission; server-side deduplication |
 | `sequence` | `0`, `1`, `2` | Ordering of records within a batch |
+| `machine_id` | `a1b2c3d4-...` | Count unique installations |
 | `platform` | `macos`, `linux`, `windows`, `wsl` | Platform distribution |
 | `arch` | `aarch64`, `x86_64` | Architecture distribution |
 | `version` | `0.1.0` | Identify version adoption |
@@ -41,7 +42,9 @@ For example, `icp deploy --mode install --environment production` records:
 ]
 ```
 
-The `batch` UUID is generated fresh each time records are transmitted and is not persisted across sends. Records within the same batch can be grouped, but there is no long-lived identifier that links activity across different transmissions.
+The `batch` UUID is generated fresh each time records are transmitted and is not persisted across sends. Records within the same batch can be grouped for server-side deduplication.
+
+The `machine_id` is a random UUID generated on first run and stored locally. It is used solely to count unique installations and is not linked to any user identity.
 
 Additional fields may be introduced in future versions. This page will be updated accordingly. The same privacy principles apply: no personally identifiable information, no project data.
 
@@ -106,6 +109,7 @@ Runtime state and event data live in the `telemetry/` data directory. Each piece
 
 ```
 telemetry/
+  machine-id                          # plain text UUID, generated on first run
   notice-shown                        # empty marker file, presence = notice was shown
   next-send-time                      # plain text UTC timestamp
   events.jsonl                        # active event log