Skip to content

Commit 20fdb14

Browse files
authored
feat!: report capture v1 results through CaptureError and on_error (#1020)
* feat!: report capture v1 results through CaptureError and on_error * test: cover _uuid7 layout for the mutation gate * fix: re-raise sync capture failures in debug mode after reporting them Also document which events verdict_summary() counts.
1 parent 29225eb commit 20fdb14

13 files changed

Lines changed: 538 additions & 120 deletions

‎posthog/__init__.py‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -313,8 +313,11 @@ def get_tags() -> Dict[str, Any]:
313313
disabled no-op global client.
314314
host: PostHog ingestion host. Defaults to the US ingestion endpoint when not
315315
set.
316-
on_error: Optional callback invoked by background consumers when event upload
317-
fails. Keep it short and non-blocking. Lifecycle methods can be called
316+
on_error: Optional callback ``(error, batch)`` invoked when event upload
317+
fails: by background consumers, or on the calling thread in ``sync_mode``.
318+
Capture failures arrive as ``CaptureError``. Without it, each failed batch
319+
logs one aggregate line. A capture that fails inside the callback logs that
320+
line instead of calling it again. Keep it short and non-blocking. Lifecycle methods can be called
318321
directly and will be deferred, but the callback must not wait for another
319322
thread or task that calls ``flush()``, ``join()``, or ``shutdown()``.
320323
debug: Enable verbose SDK logging and re-raise errors from public APIs.

‎posthog/_async_consumer.py‎

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111

1212
from ._async_request import async_send_v1_batch
1313
from .capture_compression import CaptureCompression
14+
from .capture_send import _CAPTURE_V1_PATH, _capture_loss_message
1415
from .consumer import BATCH_SIZE_LIMIT, MAX_MSG_SIZE
1516
from .request import DatetimeSerializer
1617

@@ -47,6 +48,33 @@ async def _invoke_callback(callback, *args):
4748
return result
4849

4950

51+
# True while an SDK-invoked `on_error` runs, so a capture that fails inside the
52+
# callback logs instead of re-entering it.
53+
_IN_ON_ERROR: contextvars.ContextVar[bool] = contextvars.ContextVar(
54+
"posthog_in_on_error", default=False
55+
)
56+
57+
58+
async def _report_capture_failure(
59+
on_error: Optional[Callable[..., Any]],
60+
log: logging.Logger,
61+
error: Exception,
62+
batch: list[dict[str, Any]],
63+
endpoint: str,
64+
) -> None:
65+
"""Hand a failed send to `on_error`, or log one aggregate line without one."""
66+
if on_error is None or _IN_ON_ERROR.get():
67+
log.error(_capture_loss_message(error, max(1, len(batch)), endpoint))
68+
return
69+
token = _IN_ON_ERROR.set(True)
70+
try:
71+
await _invoke_callback(on_error, error, batch)
72+
except Exception as callback_error:
73+
log.error("on_error handler failed (%s)", type(callback_error).__name__)
74+
finally:
75+
_IN_ON_ERROR.reset(token)
76+
77+
5078
async def _serialized_event_size(event: dict[str, Any]) -> int:
5179
serialized = await asyncio.to_thread(json.dumps, event, cls=DatetimeSerializer)
5280
return len(serialized.encode())
@@ -142,18 +170,9 @@ async def upload(self, batch: list[dict[str, Any]]) -> None:
142170
try:
143171
await self.request(batch)
144172
except Exception as error:
145-
self.log.error(
146-
"async capture upload failed (%s, status=%s)",
147-
type(error).__name__,
148-
getattr(error, "status", None),
173+
await _report_capture_failure(
174+
self.on_error, self.log, error, batch, _CAPTURE_V1_PATH
149175
)
150-
if self.on_error:
151-
try:
152-
await _invoke_callback(self.on_error, error, batch)
153-
except Exception as callback_error:
154-
self.log.error(
155-
"on_error handler failed (%s)", type(callback_error).__name__
156-
)
157176
finally:
158177
for _ in batch:
159178
self.queue.task_done()

‎posthog/async_client.py‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,15 @@
1111
import weakref
1212
from datetime import datetime, timezone
1313
from typing import Any, Dict, Mapping, Optional, Union
14-
from uuid import UUID, uuid4
14+
from uuid import UUID
1515

1616
from typing_extensions import Unpack
1717

1818
from ._async_consumer import (
1919
_STOP,
2020
_AsyncConsumer,
2121
_invoke_callback,
22+
_report_capture_failure,
2223
_is_processing_event,
2324
_QueuedEvent,
2425
_run_outside_processing_event,
@@ -34,6 +35,7 @@
3435
CaptureCompression,
3536
_resolve_capture_compression,
3637
)
38+
from .capture_send import _CAPTURE_V1_PATH
3739
from .client import (
3840
MAX_DICT_SIZE as _MAX_DICT_SIZE,
3941
_MINIMAL_FLAG_CALLED_EVENT_PROPERTIES,
@@ -76,7 +78,13 @@
7678
from .release_id import _resolve_release_id
7779
from .request import QuotaLimitError, determine_server_host, normalize_host
7880
from .types import FlagMetadata, FlagValue, normalize_flags_response
79-
from .utils import SizeLimitedDict, _normalize_timestamp, clean, system_context
81+
from .utils import (
82+
SizeLimitedDict,
83+
_normalize_timestamp,
84+
_uuid7,
85+
clean,
86+
system_context,
87+
)
8088
from .version import VERSION
8189

8290
__all__ = ["AsyncClient", "AsyncPosthog"]
@@ -380,7 +388,7 @@ def _normalize_uuid(self, msg: dict[str, Any]) -> str:
380388
msg["uuid"] = normalized
381389
return normalized
382390

383-
normalized = str(uuid4())
391+
normalized = str(_uuid7())
384392
msg["uuid"] = normalized
385393
return normalized
386394

@@ -576,20 +584,11 @@ async def capture_immediate(
576584
await consumer.request(error_batch)
577585
return sent_uuid
578586
except Exception as error:
579-
if self.on_error:
580-
try:
581-
await _invoke_callback(self.on_error, error, error_batch)
582-
except Exception as callback_error:
583-
self.log.error(
584-
"on_error handler failed (%s)", type(callback_error).__name__
585-
)
587+
await _report_capture_failure(
588+
self.on_error, self.log, error, error_batch, _CAPTURE_V1_PATH
589+
)
586590
if self.debug:
587591
raise
588-
self.log.error(
589-
"Immediate async capture failed (%s, status=%s)",
590-
type(error).__name__,
591-
getattr(error, "status", None),
592-
)
593592
return None
594593
finally:
595594
remaining_calls = self._immediate_callers[current] - 1

0 commit comments

Comments
 (0)