Bug 1994757 - Store the client ID in an additional plaintext file and report on regeneration

.dictionary

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 304 utf-8
+personal_ws-1.1 en 306 utf-8
 AAR
 AARs
 ABI
@@ -233,13 +233,15 @@ pdoc
 perrymcmanis
 pidcat
 pipenv
+plaintext
 polyfill
 pre
 prebuilt
 preinit
 profiler
 py
 pytest
+regenerations
 rethrow
 retransmission
 rfloor

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 [Full changelog](https://github.com/mozilla/glean/compare/v66.0.1...main)
 
+* General
+  * Store the client ID in an additional plaintext file and report on regeneration ([#3292](https://github.com/mozilla/glean/pull/3292))
+
 # v66.0.1 (2025-10-30)
 
 [Full changelog](https://github.com/mozilla/glean/compare/v66.0.0...v66.0.1)

docs/dev/SUMMARY.md

@@ -40,4 +40,5 @@
     - [Debug Pings](core/internal/debug-pings.md)
     - [Upload mechanism](core/internal/upload.md)
     - [Implementations](core/internal/implementations.md)
+    - [Client ID recovery](core/internal/client_id_recovery.md)
 - [API Documentation](api/index.md)

docs/dev/book.toml

@@ -8,7 +8,7 @@ build-dir = "book"
 create-missing = false
 
 [output.html]
-additional-css = ["../shared/glean.css", "../shared/mermaid.css"]
+additional-css = ["../shared/glean.css"]
 additional-js = ["../shared/tabs.js", "../shared/mermaid.min.js", "../shared/mermaid-init.js"]
 git-repository-url = "https://github.com/mozilla/glean"
 edit-url-template = "https://github.com/mozilla/glean/edit/main/docs/dev/{path}"

docs/dev/core/internal/client_id_recovery.md

@@ -0,0 +1,58 @@
+# Client ID recovery
+
+Currently (2025-10-31, Glean v66) we see some unexplained Glean SDK database resets.
+These are noticeable in data as client ID regenerations:
+A client application with telemetry enabled, which previously already sent data,
+regenerates its client ID on initialize and thus looks like a new client.
+
+That's undesirable and a bug.
+However we have yet to track down the actual faulty code path.
+Until that bug is found and fixed, the Glean SDK provides an extra mitigation.
+
+From Glean v66.1.0 on the SDK will store the client ID in a `client_id.txt` in the provided data path.
+Any inconsistencies in that data compared to the database will be reported
+and, if applicable, the client ID restored.
+
+**Note:** Glean v66.1.0 will only report the inconsistency, but will not restore a recovered client ID.
+This allows us to measure the impact.
+The mitigation will be enabled in a later release ([bug 1996862](https://bugzilla.mozilla.org/show_bug.cgi?id=1996862)).
+
+The exact flow of decisions is depicted in the chart below.
+The implementation is in [`glean-core/src/core/mod.rs`](https://github.com/mozilla/glean/blob/HEAD/glean-core/src/core/mod.rs#L264)
+
+```mermaid
+flowchart TD
+    A["Glean.init"] -->B
+    B{client_id.txt exists?} -->|yes| C
+    B -->|no| D
+    C["(a) load file ID"] --> E
+    D["load DB ID"] --> D3
+    D3{DB ID empty} -->|yes| D4
+    D3 -->|no| S
+    D4["generate DB ID"] --> S
+    E{valid file and ID?} -->|yes| H
+    E -->|no| G
+    G["(b) record file read error"] --> H
+    H{"(c) DB size <= 0"} -->|yes| J
+    H -->|no| F
+    J["(d) record empty DB error
+    report recovered ID: file ID"] --> Q
+    F["load DB ID"] --> N
+    L{file ID == DB ID} --> |yes| Z
+    L -->|no| T
+    N{DB ID empty?} -->|yes| O
+    N -->|no| L
+    O["(f) record regen error"] --> Q
+    P["(g) record mismatch error
+    report recovered ID: file ID"] --> S
+    Q["(e) mitigation:
+    set DB ID = file ID"] --> Z
+    S["(h) write DB ID to file"] --> Z
+    T{"DB ID == 'c0ffee'"}
+    T -->|yes| U
+    T -->|no| P
+    U["(i) record c0ffee error
+    report recovered ID: file ID"] --> Q
+
+    Z(normal operation)
+```

docs/dev/core/internal/index.md

@@ -17,6 +17,8 @@ This includes:
 * [Clearing metrics when disabling/enabling Glean](clearing.md)
 * [Database format](database.md)
 * [Payload format](payload.md)
-* [Directory structure](directory-structure.md)
+* [Directory & file structure](directory-structure.md)
 * [Debug Pings](debug-pings.md)
+* [Upload mechanism](upload.md)
 * [Implementations](implementations.md)
+* [Client ID recovery](client_id_recovery.md)

docs/dev/core/internal/upload.md

@@ -20,21 +20,17 @@ All language bindings implement ping uploading around a common API and protocol.
 
 ```mermaid
 classDiagram
-    class UploadResult {
-    }
+    class UploadResult { }
 
     class HttpResponse {
         int statusCode
     }
 
-    class UnrecoverableFailure {
-    }
+    class UnrecoverableFailure { }
 
-    class RecoverableFailure {
-    }
+    class RecoverableFailure { }
 
-    class Incapable {
-    }
+    class Incapable { }
 
     UploadResult <|-- HttpResponse
     UploadResult <|-- UnrecoverableFailure

docs/shared/mermaid-init.js

@@ -1,4 +1,39 @@
-/* This Source Code Form is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-mermaid.initialize({startOnLoad:true});
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+(() => {
+    const darkThemes = ['ayu', 'navy', 'coal'];
+    const lightThemes = ['light', 'rust'];
+
+    const classList = document.getElementsByTagName('html')[0].classList;
+
+    let lastThemeWasLight = true;
+    for (const cssClass of classList) {
+        if (darkThemes.includes(cssClass)) {
+            lastThemeWasLight = false;
+            break;
+        }
+    }
+
+    const theme = lastThemeWasLight ? 'default' : 'dark';
+    mermaid.initialize({ startOnLoad: true, theme });
+
+    // Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
+
+    for (const darkTheme of darkThemes) {
+        document.getElementById(darkTheme).addEventListener('click', () => {
+            if (lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+
+    for (const lightTheme of lightThemes) {
+        document.getElementById(lightTheme).addEventListener('click', () => {
+            if (!lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+})();