[None][fix] Cherry-pick #20777 from release/1.3: Validate telemetry deployment IDs as UUIDs

Forward-port of release/1.3 PR #20777
(release/1.3 commit 6c172f3) to main.

Adapted to main: the new payload test patches _HEARTBEAT_STOP, which main
renamed from _REPORTER_STOP.

Signed-off-by: Maxim Gluhovskoi <mgluhovskoi@nvidia.com>
Signed-off-by: Simeng Liu <simengl@nvidia.com>

Author: Mgluhovskoi

tensorrt_llm/usage/schemas/README.md

@@ -109,7 +109,7 @@ exclude these sentinel values from parallelism averages and distributions.
 | `llmApiConfigJson` | string | JSON-serialized sanitized, type-driven effective LLM API configuration. See [LLM API config capture](#llm-api-config-capture). | `'{"tensor_parallel_size":2,...}'` |
 | `llmApiConfigMetaJson` | string | JSON-serialized metadata for LLM API configuration capture. | `'{"capture_succeeded":true,...}'` |
 | `disaggRole` | ShortString | Disaggregated serving role. Empty if not disaggregated. | `""`, `"context"`, `"generation"`, `"coordinator"`, `"server_coordinator"`, `"ctx0"`, `"gen0"` |
-| `deploymentId` | ShortString | Shared ID across disaggregated workers. Empty if not disaggregated. | `""`, `"dep-abc123"` |
+| `deploymentId` | ShortString | Shared disaggregated deployment UUID, normalized to lowercase hex. Empty if unset or invalid. | `""`, `"7cd46f928e324879b82a7cabd3c0ecde"` |
 
 ##### Architecture privacy policy
 
@@ -163,7 +163,7 @@ exit, a terminal report, or telemetry opt-out, with no heartbeat-count limit.
 | `seq` | PositiveInt | Zero-based heartbeat sequence number, saturating at uint32 max. | `0`, `1`, `42` |
 | `ingressPoint` | ShortString | Invocation boundary for the process session. | `"cli_serve"` |
 | `disaggRole` | ShortString | Disaggregated role: `context`, `generation`, `coordinator`, `server_coordinator`, or compatible legacy values such as `ctx0`/`gen0`. | `"context"` |
-| `deploymentId` | ShortString | Optional shared disaggregated deployment ID. | `"dep-abc123"` |
+| `deploymentId` | ShortString | Optional shared disaggregated deployment UUID. | `"7cd46f928e324879b82a7cabd3c0ecde"` |
 
 Every heartbeat also contains the five aggregate LLM lifecycle counters above.
 
@@ -183,7 +183,7 @@ outcome. Missing terminal events remain unknown; they are not confirmed crashes.
 | `reportingSource` | enum | `self`, `supervisor`, or `executor_proxy`. |
 | `ingressPoint` | ShortString | Entry point copied onto the terminal event so terminal-only early failures remain attributable. |
 | `disaggRole` | ShortString | Disaggregated role (`context`, `generation`, `coordinator`, `server_coordinator`, or compatible legacy `ctx0`/`gen0`), or empty when unavailable/not applicable. |
-| `deploymentId` | ShortString | Optional shared disaggregated deployment ID. |
+| `deploymentId` | ShortString | Optional shared disaggregated deployment UUID. |
 
 Every terminal report also contains the five aggregate LLM lifecycle counters
 above. Delivery is best-effort and waits no more than 0.5 seconds; the local
@@ -310,7 +310,13 @@ over time.
 | `TRTLLM_USAGE_HEARTBEAT_INTERVAL` | `600` | Heartbeat interval in seconds. |
 | `TRTLLM_USAGE_FORCE_ENABLED` | `0` | Set to `1` to force-enable telemetry in CI/test environments. |
 | `TRTLLM_DISAGG_ROLE` | unset | Disaggregated serving role (`context`, `generation`, `coordinator`, `server_coordinator`, or compatible legacy values such as `ctx0`/`gen0`). |
-| `TRTLLM_DISAGG_DEPLOYMENT_ID` | unset | Shared deployment ID across disaggregated workers. |
+| `TRTLLM_DISAGG_DEPLOYMENT_ID` | unset | Shared deployment UUID across disaggregated workers. Invalid values are reported as an empty ID. |
+
+The disaggregated launcher generates a random deployment UUID and shares it
+through the environment. Custom launchers can also supply a shared UUID via
+`TRTLLM_DISAGG_DEPLOYMENT_ID`. Telemetry validates it with `uuid.UUID` and emits
+32 lowercase hexadecimal characters, or an empty string if invalid. This checks
+format, not who generated the UUID or whether it contains encoded identifying data.
 
 ## For Developers: Adding a New Field
 

tensorrt_llm/usage/usage_lib.py

@@ -85,6 +85,14 @@
 _T = TypeVar("_T")
 
 
+def _get_disagg_deployment_id() -> str:
+    """Return the environment's deployment UUID as lowercase hex, or empty if invalid."""
+    try:
+        return uuid.UUID(os.environ.get(_DISAGG_DEPLOYMENT_ID_ENV, "")).hex
+    except ValueError:
+        return ""
+
+
 @dataclass(frozen=True)
 class TerminalOutcome:
     """One typed process-boundary or previously observed terminal outcome."""
@@ -794,7 +802,7 @@ def _refresh_metadata_unlocked(self) -> None:
         if not self.disagg_role:
             self.disagg_role = os.environ.get(_DISAGG_ROLE_ENV, "")
         if not self.deployment_id:
-            self.deployment_id = os.environ.get(_DISAGG_DEPLOYMENT_ID_ENV, "")
+            self.deployment_id = _get_disagg_deployment_id()
 
         normalized_role = self.disagg_role.lower()
         if self.component == "server" and (
@@ -1071,9 +1079,7 @@ def _empty_event_snapshot(usage_context: str = "") -> dict[str, Any]:
     return {
         "ingressPoint": _clamp_str(usage_context, schema._SHORT_STR),
         "disaggRole": _clamp_str(os.environ.get(_DISAGG_ROLE_ENV, ""), schema._SHORT_STR),
-        "deploymentId": _clamp_str(
-            os.environ.get(_DISAGG_DEPLOYMENT_ID_ENV, ""), schema._SHORT_STR
-        ),
+        "deploymentId": _get_disagg_deployment_id(),
         "llmInitializationAttempts": 0,
         "llmInstancesCreated": 0,
         "activeLlmInstances": 0,

tests/unittest/usage/test_reporter.py

@@ -595,31 +595,54 @@ def fake_send(payload):
 
 
 class TestDisaggMetadata:
-    """Verify _background_reporter() reads disagg env vars into initial report."""
+    """Verify disagg correlation accepts UUIDs but excludes arbitrary identifying text."""
 
-    def test_disagg_env_vars_appear_in_payload(self, monkeypatch, reporter_session):
-        """Disagg env vars appear as disaggRole and deploymentId in payload."""
+    @pytest.mark.parametrize(
+        ("deployment_id", "expected"),
+        [
+            (None, ""),
+            ("", ""),
+            ("/home/alice/model", ""),
+            ("alice@example.com", ""),
+            ("a" * 128, ""),
+            ("7cd46f928e324879b82a7cabd3c0ecd", ""),
+            ("7cd46f928e324879b82a7cabd3c0ecdZ", ""),
+            ("7cd46f928e324879b82a7cabd3c0ecde", "7cd46f928e324879b82a7cabd3c0ecde"),
+            ("7CD46F92-8E32-4879-B82A-7CABD3C0ECDE", "7cd46f928e324879b82a7cabd3c0ecde"),
+        ],
+    )
+    def test_deployment_id_validated_in_payloads(
+        self, monkeypatch, reporter_session, deployment_id, expected
+    ):
+        """Initial, heartbeat, and exit payloads contain only normalized UUIDs or empty IDs."""
         monkeypatch.setenv("TRTLLM_DISAGG_ROLE", "context")
-        monkeypatch.setenv("TRTLLM_DISAGG_DEPLOYMENT_ID", "abc123")
-
-        captured = {}
-
-        def fake_send(payload):
-            captured.update(payload)
-
-        stop_event = threading.Event()
-        stop_event.set()
+        if deployment_id is None:
+            monkeypatch.delenv("TRTLLM_DISAGG_DEPLOYMENT_ID", raising=False)
+        else:
+            monkeypatch.setenv("TRTLLM_DISAGG_DEPLOYMENT_ID", deployment_id)
+        assert usage_lib._empty_event_snapshot()["deploymentId"] == expected
+        captured = []
+        stop_event = MagicMock()
+        stop_event.wait.side_effect = [False, True]
 
         with (
-            patch.object(usage_lib, "_send_to_gxt", side_effect=fake_send),
+            patch.object(usage_lib, "_send_to_gxt", side_effect=captured.append),
             patch.object(usage_lib, "_HEARTBEAT_STOP", stop_event),
         ):
             usage_lib._background_reporter(None, None, "")
+            usage_lib.report_exit(usage_lib.TerminalOutcome("clean", exit_code_known=True))
 
-        assert captured, "No payload was captured"
-        params = captured["events"][0]["parameters"]
-        assert params["disaggRole"] == "context"
-        assert params["deploymentId"] == "abc123"
+        events = [event for payload in captured for event in payload["events"]]
+        assert [event["name"] for event in events] == [
+            "trtllm_initial_report",
+            "trtllm_heartbeat",
+            "trtllm_exit_report",
+        ]
+        for event in events:
+            assert event["parameters"]["disaggRole"] == "context"
+            assert event["parameters"]["deploymentId"] == expected
+        if deployment_id and not expected:
+            assert deployment_id not in json.dumps(captured)
 
     def test_disagg_payload_includes_llm_api_config_json(self, monkeypatch, reporter_session):
         """Disagg payloads retain sanitized LLM API config JSON fields."""
@@ -630,7 +653,8 @@ class _DisaggTelemetryArgs(BaseModel):
             )
 
         monkeypatch.setenv("TRTLLM_DISAGG_ROLE", "generation")
-        monkeypatch.setenv("TRTLLM_DISAGG_DEPLOYMENT_ID", "deploy123")
+        deployment_id = usage_lib.uuid.uuid4()
+        monkeypatch.setenv("TRTLLM_DISAGG_DEPLOYMENT_ID", deployment_id.hex)
 
         captured = {}
 
@@ -649,7 +673,7 @@ def fake_send(payload):
         assert captured, "No payload was captured"
         params = captured["events"][0]["parameters"]
         assert params["disaggRole"] == "generation"
-        assert params["deploymentId"] == "deploy123"
+        assert params["deploymentId"] == deployment_id.hex
         assert json.loads(params["llmApiConfigJson"]) == {"tensor_parallel_size": 2}
         meta = json.loads(params["llmApiConfigMetaJson"])
         assert meta["capture_succeeded"] is True
@@ -1286,12 +1310,17 @@ def test_terminal_event_uses_shared_session_id(self, monkeypatch, enable_telemet
         assert event["parameters"]["ingressPoint"] == "cli_serve"
         assert event["parameters"]["exitCode"] == 130
 
+    @pytest.mark.parametrize("valid_id", [False, True])
     def test_terminal_event_contains_correlation_and_counter_snapshot(
-        self, monkeypatch, enable_telemetry
+        self, monkeypatch, enable_telemetry, valid_id
     ):
         """Terminal-only sessions carry enough state for independent analysis."""
         monkeypatch.setenv("TRTLLM_DISAGG_ROLE", "ctx0")
-        monkeypatch.setenv("TRTLLM_DISAGG_DEPLOYMENT_ID", "deployment")
+        deployment_id = usage_lib.uuid.uuid4()
+        monkeypatch.setenv(
+            "TRTLLM_DISAGG_DEPLOYMENT_ID",
+            str(deployment_id) if valid_id else "/home/alice/deployment",
+        )
         assert usage_lib.record_llm_initialization_attempt(default_usage_context="cli_serve")
         usage_lib.record_llm_initialization_failure()
 
@@ -1308,7 +1337,8 @@ def test_terminal_event_contains_correlation_and_counter_snapshot(
             )
 
         params = sent[0]["events"][0]["parameters"]
-        assert params["deploymentId"] == "deployment"
+        assert params["deploymentId"] == (deployment_id.hex if valid_id else "")
+        assert "/home/alice/deployment" not in json.dumps(sent)
         assert params["disaggRole"] == "ctx0"
         assert params["llmInitializationAttempts"] == 1
         assert params["llmInitializationFailures"] == 1