fix: warn once without the value when replacing an invalid event uuid

An invalid caller uuid is still replaced with a generated UUIDv7, but the
SDK now logs one warning that names the rule instead of an error that
echoes the value. An empty string counts as unset and gets a generated
uuid without a log. Client and AsyncClient share one helper.

Author: eli-r-ph

.sampo/changesets/invalid-uuid-warning.md

@@ -0,0 +1,5 @@
+---
+pypi/posthog: major
+---
+
+An invalid event `uuid` is still replaced with a generated one, but the SDK now logs one warning instead of an error, and the warning no longer includes the value. An empty string `uuid` counts as unset, so the SDK generates one without logging. `AsyncPosthog` follows the same rules.

docs/migration-7.x-to-8.0.md

@@ -102,7 +102,7 @@ When the whole request is over the billing limit, capture returns a `402` with n
 
 - Each event needs its own uuid. Capture rejects a whole batch that contains the same uuid twice, so the other events in that batch are lost too.
 - The SDK accepts a uuid with hyphens, 32 hex digits, `{...}` braces or a `urn:uuid:` prefix, in any case. It sends the lowercase hyphenated form and returns that form from `capture`.
-- Any other value is replaced with a generated uuid, and the SDK logs an error. This applies to `AsyncPosthog` too.
+- Any other value is replaced with a generated uuid, and the SDK logs one warning that names the rule, not the value. An empty string counts as unset, so the SDK generates a uuid without a warning. This applies to `AsyncPosthog` too.
 - Generated uuids are UUIDv7.
 
 ## Session and window IDs

posthog/async_client.py

@@ -39,11 +39,11 @@
 )
 from .capture_event import (
     _build_event_defaults,
-    _canonical_event_uuid,
     _event_options,
     _EventDefaults,
     _fill_event_defaults,
     _merge_groups,
+    _resolve_event_uuid,
 )
 from .capture_send import _CAPTURE_AI_V1_PATH, _CAPTURE_V1_PATH
 from .client import (
@@ -98,7 +98,6 @@
 from .utils import (
     SizeLimitedDict,
     _normalize_timestamp,
-    _uuid7,
     clean,
     system_context,
 )
@@ -447,18 +446,7 @@ def enqueue_on_bound_loop() -> None:
         return admitted.result()
 
     def _normalize_uuid(self, msg: dict[str, Any]) -> str:
-        raw_uuid = msg.pop("uuid", None)
-        if raw_uuid is not None:
-            normalized = _canonical_event_uuid(raw_uuid)
-            if normalized is None:
-                self.log.error(
-                    "Invalid UUID %r. Falling back to a generated UUID.", raw_uuid
-                )
-            else:
-                msg["uuid"] = normalized
-                return normalized
-
-        normalized = str(_uuid7())
+        normalized = _resolve_event_uuid(msg.pop("uuid", None))
         msg["uuid"] = normalized
         return normalized
 

posthog/capture_event.py

@@ -26,7 +26,7 @@
 from typing import Any, Optional
 from uuid import UUID
 
-from posthog.utils import _normalize_timestamp
+from posthog.utils import _normalize_timestamp, _uuid7
 from posthog.utils import clean as _clean
 
 log = logging.getLogger("posthog")
@@ -78,6 +78,24 @@ def _canonical_event_uuid(value: Any) -> Optional[str]:
     return str(UUID(value.lower()))
 
 
+def _resolve_event_uuid(value: Any) -> str:
+    """Return the canonical form of a caller's event uuid, or a generated one.
+
+    A missing or empty uuid is generated silently. An invalid one is replaced
+    and logs one warning. The warning names the rule and not the value,
+    because callers can put their own data in the uuid field.
+    """
+    if value is not None and value != "":
+        canonical = _canonical_event_uuid(value)
+        if canonical is not None:
+            return canonical
+        log.warning(
+            "Event uuid is not a valid UUID string or uuid.UUID. "
+            "Sending the event with a generated UUID."
+        )
+    return str(_uuid7())
+
+
 def _json_type_name(value: Any) -> str:
     """Name a value's JSON type, the same names posthog-go and posthog-rs log."""
     if isinstance(value, bool):

posthog/client.py

@@ -36,10 +36,10 @@
 )
 from posthog.capture_event import (
     _build_event_defaults,
-    _canonical_event_uuid,
     _event_options,
     _fill_event_defaults,
     _merge_groups,
+    _resolve_event_uuid,
 )
 from posthog.capture_send import (
     _CAPTURE_AI_V1_PATH,
@@ -137,7 +137,6 @@
     SizeLimitedDict,
     clean,
     _normalize_timestamp,
-    _uuid7,
     guess_timezone as guess_timezone,
     system_context,
 )
@@ -274,15 +273,6 @@ def get_identity_state(passed) -> tuple[str, bool]:
     return (str(uuid4()), True)
 
 
-def _stringify_event_uuid(value) -> str:
-    canonical = _canonical_event_uuid(value)
-    if canonical is None:
-        raise ValueError(
-            f"Invalid event uuid {value!r}. Expected a valid UUID string or uuid.UUID instance."
-        )
-    return canonical
-
-
 def _personless_options(personless: bool) -> dict[str, Any]:
     """The lowest option layer: no person profile for a generated distinct ID."""
     return {"process_person_profile": False} if personless else {}
@@ -2475,17 +2465,8 @@ def _reinit_after_fork(self):
     def _normalize_event_uuid(self, msg):
         # type: (...) -> None
         """Ensure `msg["uuid"]` is a valid uuid string, generating one if missing or invalid."""
-        if "uuid" in msg:
-            uuid = msg.pop("uuid")
-            if uuid is not None:
-                try:
-                    msg["uuid"] = _stringify_event_uuid(uuid)
-                except ValueError as e:
-                    self.log.error("%s Falling back to a generated UUID.", e)
-
-        if "uuid" not in msg:
-            # Always send a uuid, so we can always return one
-            msg["uuid"] = str(_uuid7())
+        # Always send a uuid, so we can always return one
+        msg["uuid"] = _resolve_event_uuid(msg.pop("uuid", None))
 
     def _report_capture_failure(
         self, error: Exception, batch: list[dict], endpoint: str

posthog/test/test_async_client.py

@@ -72,6 +72,26 @@ async def send_batch(api_key, host, batch, **kwargs):
     assert event["uuid"] == event_uuid
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "supplied, warnings",
+    [("not-a-uuid-secret-1", 1), (123, 1), ("", 0), (None, 0)],
+)
+async def test_capture_replaces_unusable_uuid_and_warns_only_when_invalid(
+    caplog, supplied, warnings
+):
+    client = AsyncPosthog("test-key", send=False)
+    with caplog.at_level(logging.WARNING, logger="posthog"):
+        event_uuid = client.capture("async event", distinct_id="user-1", uuid=supplied)
+    await client.shutdown()
+
+    assert UUID(event_uuid).version == 7
+    logged = [r for r in caplog.records if r.levelno >= logging.WARNING]
+    assert len(logged) == warnings
+    assert all(r.levelname == "WARNING" for r in logged)
+    assert all(str(supplied) not in r.getMessage() for r in logged)
+
+
 def test_capture_from_worker_thread_wakes_loop_bound_queue():
     script = r"""
 import asyncio

posthog/test/test_client.py

@@ -476,18 +476,17 @@ def test_capture_sends_and_returns_canonical_uuid(self, _name, supplied):
 
     @parameterized.expand(
         [
-            ("empty string", ""),
-            ("invalid string", "not-a-uuid"),
+            ("invalid string", "not-a-uuid-secret-1"),
             ("short string", "1234"),
             ("integer", 123),
         ]
     )
-    def test_capture_with_invalid_uuid_logs_and_falls_back_to_generated_uuid(
+    def test_capture_with_invalid_uuid_warns_and_falls_back_to_generated_uuid(
         self, _name, invalid_uuid
     ):
         with patch_capture_send("client") as mock_post:
             client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True)
-            with self.assertLogs("posthog", level="ERROR") as logs:
+            with self.assertLogs("posthog", level="WARNING") as logs:
                 msg_uuid = client.capture(
                     "python test event", distinct_id="distinct_id", uuid=invalid_uuid
                 )
@@ -498,18 +497,24 @@ def test_capture_with_invalid_uuid_logs_and_falls_back_to_generated_uuid(
             msg = sent_batch(mock_post)[0]
             self.assertEqual(msg["uuid"], msg_uuid)
             self.assertNotEqual(msg["uuid"], str(invalid_uuid))
-            self.assertTrue(
-                any(
-                    f"Invalid event uuid {invalid_uuid!r}" in message
-                    and "Expected a valid UUID string or uuid.UUID instance" in message
-                    and "Falling back to a generated UUID" in message
-                    for message in logs.output
+            uuid_warnings = [r for r in logs.records if "Event uuid" in r.getMessage()]
+            self.assertEqual(len(uuid_warnings), 1)
+            self.assertEqual(uuid_warnings[0].levelname, "WARNING")
+            self.assertNotIn(str(invalid_uuid), uuid_warnings[0].getMessage())
+
+    def test_capture_with_empty_uuid_generates_one_without_logging(self):
+        with patch_capture_send("client") as mock_post:
+            client = Client(FAKE_TEST_API_KEY, on_error=self.set_fail, sync_mode=True)
+            with self.assertNoLogs("posthog", level="WARNING"):
+                msg_uuid = client.capture(
+                    "python test event", distinct_id="distinct_id", uuid=""
                 )
-            )
+
+            self.assertEqual(UUID(msg_uuid).version, 7)
+            self.assertEqual(sent_batch(mock_post)[0]["uuid"], msg_uuid)
 
     @parameterized.expand(
         [
-            ("empty string", ""),
             ("invalid string", "not-a-uuid"),
             ("short string", "1234"),
             ("integer", 123),
@@ -518,7 +523,7 @@ def test_capture_with_invalid_uuid_logs_and_falls_back_to_generated_uuid(
     def test_capture_with_invalid_uuid_falls_back_in_debug(self, _name, invalid_uuid):
         with patch_capture_send("client") as mock_post:
             client = Client(FAKE_TEST_API_KEY, debug=True, sync_mode=True)
-            with self.assertLogs("posthog", level="ERROR"):
+            with self.assertLogs("posthog", level="WARNING"):
                 msg_uuid = client.capture(
                     "python test event", distinct_id="distinct_id", uuid=invalid_uuid
                 )