Skip to content

Commit 4d32397

Browse files
authored
feat!: exception level, keyword-only args, uuid and geoip (#1046)
* fix: make request.post and request.flags arguments keyword-only * feat: add a level argument to capture_exception and ignore reserved exception properties * feat: warn when a non-string session or window id is dropped * docs: describe the exception level, keyword-only request args and session id warning * 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. * fix: treat a per-call disable_geoip as a value of the event A disable_geoip argument now fills $geoip_disable as the event's own value: above context tags, super_properties and the client setting, and below a $geoip_disable in the call's properties. disable_geoip=False now sends $geoip_disable: false. Client and AsyncClient share the layer in _build_event_defaults.
1 parent 0e7afbb commit 4d32397

18 files changed

Lines changed: 363 additions & 149 deletions
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
pypi/posthog: major
3+
---
4+
5+
A `disable_geoip` argument to a call now counts as a value of that event. It wins over a `$geoip_disable` in context tags or `super_properties`, and a `$geoip_disable` in the call's own `properties` still wins over it. `disable_geoip=False` now sends `$geoip_disable: false`, so it turns GeoIP lookup on for that event even when a context tag or `super_properties` turns it off. The client's `disable_geoip` setting keeps its place below every caller value. `AsyncPosthog` follows the same rules.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
pypi/posthog: major
3+
---
4+
5+
`capture_exception` takes a `level=` argument on `Client`, `AsyncPosthog` and the module, which sets `$exception_level` (default `"error"`). Reserved exception properties passed in `properties`, such as `$exception_list` and `$exception_level`, are now ignored. In 7.x they overrode the SDK's values with a `DeprecationWarning`. `AsyncPosthog.capture_exception` now sends `$exception_level`.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
pypi/posthog: major
3+
---
4+
5+
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.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
pypi/posthog: major
3+
---
4+
5+
The parameters after `path` in `posthog.request.post` and after `host` in `posthog.request.flags` are keyword-only. With `gzip` removed, a 7.x call that passed them by position bound them to the wrong parameter. It now raises `TypeError`.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
pypi/posthog: major
3+
---
4+
5+
A `$session_id` or `$window_id` that is not a string is not sent, because capture v1 would reject the whole batch, and the SDK logs a warning for each one. The warning names the key and the value's type, not the value. `None` counts as unset and drops without a warning. An empty string is sent. In 7.x these values were sent as properties.

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

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ Read the checklist first, then the sections that apply to you.
99
You need to change code if your app does any of these:
1010

1111
- passes `Client` or `AsyncPosthog` constructor arguments by position after `host`
12+
- calls `posthog.request.post` or `posthog.request.flags` with positional arguments after `path` or `host`
13+
- sets `$exception_level` or another reserved exception property in `capture_exception(properties=...)`
1214
- sets `capture_mode`, `POSTHOG_CAPTURE_MODE` or `gzip`
1315
- imports `CaptureV1Error`, `posthog.capture_v1`, `request.batch_post`, `EVENTS_ENDPOINT` or `AI_EVENTS_ENDPOINT`
1416
- sends events to a self-hosted PostHog that does not serve the capture v1 endpoints
@@ -58,7 +60,7 @@ To find MCP traffic, filter on the `$mcp_*` events and properties instead of `$l
5860
| `CaptureV1Error` (`from posthog.capture_v1 import CaptureV1Error`) | `CaptureError` (`from posthog import CaptureError`). There is no alias. |
5961
| `posthog.capture_v1` | `posthog.capture_event` and `posthog.capture_send` |
6062
| `request.batch_post`, `async_batch_post`, `EVENTS_ENDPOINT`, `AI_EVENTS_ENDPOINT` | Nothing. Send events through a client. |
61-
| The `gzip` parameter of `request.post` and `request.flags` | Nothing. |
63+
| The `gzip` parameter of `request.post` and `request.flags` | Nothing. The parameters after `path` in `post` and after `host` in `flags` are keyword-only, so a 7.x call that passes them by position raises `TypeError`. |
6264
| The `backoff` dependency | Add it to your own requirements if your code imports it. |
6365

6466
The `posthoganalytics` package has the same changes. For example, import `CaptureError` from `posthoganalytics`.
@@ -100,7 +102,7 @@ When the whole request is over the billing limit, capture returns a `402` with n
100102

101103
- 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.
102104
- 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`.
103-
- Any other value is replaced with a generated uuid, and the SDK logs an error. This applies to `AsyncPosthog` too.
105+
- 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.
104106
- Generated uuids are UUIDv7.
105107

106108
## Session and window IDs
@@ -110,7 +112,13 @@ The SDK moves them out of `properties` for you.
110112

111113
- A string is sent as given, including `""`.
112114
- `None` counts as unset and is removed.
113-
- Any other value is removed and not sent, because capture would reject the whole batch. 7.x sent it as a property.
115+
- Any other value is removed and not sent, because capture would reject the whole batch. 7.x sent it as a property. The SDK logs a warning for each one, with the key and the value's type but not the value.
116+
117+
## Exceptions
118+
119+
- `capture_exception` takes a `level=` argument on `Client`, `AsyncPosthog` and the module. It sets `$exception_level`, for example `"warning"` or `"fatal"`. The default is `"error"`, and an unknown value counts as unset.
120+
- `capture_exception` ignores reserved exception properties in `properties`, such as `$exception_list`, `$exception_level` and `$exception_source`. In 7.x they overrode the SDK's values, with a `DeprecationWarning`. Use `level=` instead of `$exception_level`.
121+
- `AsyncPosthog.capture_exception` now sends `$exception_level`.
114122

115123
## Event options
116124

@@ -141,10 +149,10 @@ Capture v1 sends processing options in an `options` object, next to `properties`
141149

142150
Values apply in this order. Steps 2 to 4 fill only the options and properties that the steps before them left unset:
143151

144-
1. the `options` and `properties` of the call
152+
1. the `options` and `properties` of the call, then the call's `disable_geoip` argument, which fills `$geoip_disable`
145153
2. context options and tags
146154
3. `super_options` and `super_properties`
147-
4. values the SDK sets: `$is_server` from `is_server`, `$geoip_disable` from `disable_geoip`, system properties such as `$os` and `$python_version`, `options.process_person_profile = false` for events without a distinct ID, and `$release_id` from `POSTHOG_RELEASE_ID`
155+
4. values the SDK sets: `$is_server` from `is_server`, `$geoip_disable` from the client's `disable_geoip` setting, system properties such as `$os` and `$python_version`, `options.process_person_profile = false` for events without a distinct ID, and `$release_id` from `POSTHOG_RELEASE_ID`
148156
5. `before_send`, which sees the result of steps 1 to 4 and can change or remove any of it
149157
6. legacy properties, which fill unset options and are then removed
150158

@@ -157,6 +165,7 @@ These changes follow from this order:
157165

158166
- Properties passed to a call now override `super_properties`. `super_properties` can no longer change `$lib` or `$lib_version`.
159167
- A `$is_server`, `$geoip_disable` or system property such as `$os` that you set in a call or a context tag now wins over the SDK's value. In 7.x the SDK overwrote it. `super_properties` win over the SDK's value too, so `super_properties={"$geoip_disable": False}` turns GeoIP lookup on for events, even with `disable_geoip=True`.
168+
- A `disable_geoip` argument to a call belongs to that event, so it wins over context tags and `super_properties`. A `$geoip_disable` in the call's own `properties` still wins over it. `disable_geoip=False` now sends `$geoip_disable: false`. In 7.x it sent no `$geoip_disable` property.
160169
- The `groups` argument merges into a `$groups` property of the call, and wins key by key. In 7.x it replaced the property. MCP events merge their identity's groups into a custom `$groups` property the same way.
161170
- A `$set`, `$set_once`, `$groups` or `$group_set` in `super_properties` no longer replaces the whole value of the call. The two merge, and the call wins key by key.
162171
- An event without a distinct ID gets `options.process_person_profile = false`. A `$process_person_profile: true` property no longer turns person processing back on. Set the option instead.

‎posthog/__init__.py‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -786,17 +786,21 @@ def alias(
786786

787787
def capture_exception(
788788
exception: Optional[ExceptionArg] = None,
789+
*,
790+
level: Optional[str] = None,
789791
**kwargs: Unpack[OptionalCaptureArgs],
790792
) -> Optional[str]:
791793
"""
792794
Capture exceptions that happen in your code.
793795
794796
Args:
795797
exception: The exception to capture. If not provided, the current exception is captured via `sys.exc_info()`
798+
level: The ``$exception_level``, such as ``"warning"`` or ``"fatal"``.
799+
Defaults to ``"error"``. An unknown value counts as unset.
796800
**kwargs: Optional capture arguments including distinct_id, properties,
797801
timestamp, uuid, groups, flags, send_feature_flags, disable_geoip, and options.
798-
Overriding reserved exception properties through ``properties`` is
799-
deprecated and will stop working in the next major version.
802+
Reserved exception properties in ``properties``, such as
803+
``$exception_list`` and ``$exception_level``, are ignored.
800804
801805
Details:
802806
Capture exception is idempotent - if it is called twice with the same exception instance, only a occurrence will be tracked in posthog. This is because, generally, contexts will cause exceptions to be captured automatically. However, to ensure you track an exception, if you catch and do not re-raise it, capturing it manually is recommended, unless you are certain it will have crossed a context boundary (e.g. by existing a `with posthog.new_context():` block already). If the passed exception was raised and caught, the captured stack trace will consist of every frame between where the exception was raised and the point at which it is captured (the "traceback"). If the passed exception was never raised, e.g. if you call `posthog.capture_exception(ValueError("Some Error"))`, the stack trace captured will be the full stack trace at the moment the exception was captured. Note that heavy use of contexts will lead to truncated stack traces, as the exception will be captured by the context entered most recently, which may not be the point you catch the exception for the final time in your code. It's recommended to use contexts sparingly, for this reason. `capture_exception` takes the same set of optional arguments as `capture`.
@@ -814,7 +818,7 @@ def capture_exception(
814818
Events
815819
"""
816820

817-
return _proxy("capture_exception", exception=exception, **kwargs)
821+
return _proxy("capture_exception", exception=exception, level=level, **kwargs)
818822

819823

820824
def feature_enabled(

‎posthog/async_client.py‎

Lines changed: 16 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -40,11 +40,11 @@
4040
)
4141
from .capture_event import (
4242
_build_event_defaults,
43-
_canonical_event_uuid,
4443
_event_options,
4544
_EventDefaults,
4645
_fill_event_defaults,
4746
_merge_groups,
47+
_resolve_event_uuid,
4848
)
4949
from .capture_send import _CAPTURE_AI_V1_PATH, _CAPTURE_V1_PATH
5050
from .client import (
@@ -77,7 +77,9 @@
7777
DEFAULT_CODE_VARIABLES_IGNORE_PATTERNS,
7878
DEFAULT_CODE_VARIABLES_MASK_PATTERNS,
7979
DEFAULT_CODE_VARIABLES_MASK_URL_CREDENTIALS,
80+
_exception_level,
8081
_get_current_otel_span_properties,
82+
_without_reserved_exception_properties,
8183
exc_info_from_error,
8284
exception_is_already_captured,
8385
exceptions_from_error_tuple,
@@ -97,7 +99,6 @@
9799
from .utils import (
98100
SizeLimitedDict,
99101
_normalize_timestamp,
100-
_uuid7,
101102
clean,
102103
system_context,
103104
)
@@ -452,18 +453,7 @@ def enqueue_on_bound_loop() -> None:
452453
return admitted.result()
453454

454455
def _normalize_uuid(self, msg: dict[str, Any]) -> str:
455-
raw_uuid = msg.pop("uuid", None)
456-
if raw_uuid is not None:
457-
normalized = _canonical_event_uuid(raw_uuid)
458-
if normalized is None:
459-
self.log.error(
460-
"Invalid UUID %r. Falling back to a generated UUID.", raw_uuid
461-
)
462-
else:
463-
msg["uuid"] = normalized
464-
return normalized
465-
466-
normalized = str(_uuid7())
456+
normalized = _resolve_event_uuid(msg.pop("uuid", None))
467457
msg["uuid"] = normalized
468458
return normalized
469459

@@ -538,8 +528,6 @@ def _event_defaults(
538528
disable_geoip: Optional[bool] = None,
539529
system_properties: Optional[dict[str, Any]] = None,
540530
) -> _EventDefaults:
541-
if disable_geoip is None:
542-
disable_geoip = self.disable_geoip
543531
return _build_event_defaults(
544532
super_properties=self.super_properties,
545533
super_options=self.super_options,
@@ -549,7 +537,8 @@ def _event_defaults(
549537
derived_options=derived_options,
550538
property_allowlist=property_allowlist,
551539
is_server=self.is_server,
552-
disable_geoip=disable_geoip,
540+
disable_geoip=self.disable_geoip,
541+
call_disable_geoip=disable_geoip,
553542
system_properties=system_properties,
554543
)
555544

@@ -880,9 +869,16 @@ def _enqueue_built_event(
880869
def capture_exception(
881870
self,
882871
exception: Optional[ExceptionArg] = None,
872+
*,
873+
level: Optional[str] = None,
883874
**kwargs: Unpack[OptionalCaptureArgs],
884875
) -> Optional[str]:
885-
"""Capture an exception. This method never raises, including in debug mode."""
876+
"""Capture an exception. This method never raises, including in debug mode.
877+
878+
``level`` sets ``$exception_level`` and defaults to ``"error"``. An unknown
879+
value counts as unset. Reserved exception properties in ``properties``,
880+
such as ``$exception_list`` and ``$exception_level``, are ignored.
881+
"""
886882
try:
887883
if exception is not None and exception_is_already_captured(exception):
888884
self.log.debug("Exception already captured, skipping")
@@ -904,8 +900,9 @@ def capture_exception(
904900
)
905901
exceptions = event["exception"]["values"]
906902
properties = {
903+
**_without_reserved_exception_properties(kwargs.get("properties")),
907904
"$exception_list": exceptions,
908-
**(kwargs.get("properties") or {}),
905+
"$exception_level": _exception_level(None, level),
909906
}
910907
context_enabled = get_capture_exception_code_variables_context()
911908
context_mask = get_code_variables_mask_patterns_context()

‎posthog/capture_event.py‎

Lines changed: 51 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
from typing import Any, Optional
2727
from uuid import UUID
2828

29-
from posthog.utils import _normalize_timestamp
29+
from posthog.utils import _normalize_timestamp, _uuid7
3030
from posthog.utils import clean as _clean
3131

3232
log = logging.getLogger("posthog")
@@ -78,6 +78,37 @@ def _canonical_event_uuid(value: Any) -> Optional[str]:
7878
return str(UUID(value.lower()))
7979

8080

81+
def _resolve_event_uuid(value: Any) -> str:
82+
"""Return the canonical form of a caller's event uuid, or a generated one.
83+
84+
A missing or empty uuid is generated silently. An invalid one is replaced
85+
and logs one warning. The warning names the rule and not the value,
86+
because callers can put their own data in the uuid field.
87+
"""
88+
if value is not None and value != "":
89+
canonical = _canonical_event_uuid(value)
90+
if canonical is not None:
91+
return canonical
92+
log.warning(
93+
"Event uuid is not a valid UUID string or uuid.UUID. "
94+
"Sending the event with a generated UUID."
95+
)
96+
return str(_uuid7())
97+
98+
99+
def _json_type_name(value: Any) -> str:
100+
"""Name a value's JSON type, the same names posthog-go and posthog-rs log."""
101+
if isinstance(value, bool):
102+
return "bool"
103+
if isinstance(value, (int, float)):
104+
return "number"
105+
if isinstance(value, (list, tuple)):
106+
return "array"
107+
if isinstance(value, Mapping):
108+
return "object"
109+
return type(value).__name__
110+
111+
81112
def _event_options(value: Any) -> dict[str, Any]:
82113
"""Return a copy of a caller's ``options``, or ``{}`` when it is not a dict."""
83114
if value is None:
@@ -93,7 +124,7 @@ def _event_options(value: Any) -> dict[str, Any]:
93124

94125
@dataclass(frozen=True)
95126
class _EventDefaults:
96-
"""Context, global and SDK-derived values for one event, highest layer first.
127+
"""Per-call, context, global and SDK-derived values for one event, highest layer first.
97128
98129
They fill in before ``before_send``, so the hook sees them and can change
99130
or remove them. The event's own values win over every default.
@@ -115,9 +146,18 @@ def _build_event_defaults(
115146
property_allowlist: Optional[Collection[str]] = None,
116147
is_server: bool = False,
117148
disable_geoip: bool = False,
149+
call_disable_geoip: Optional[bool] = None,
118150
system_properties: Optional[Mapping[str, Any]] = None,
119151
) -> _EventDefaults:
120-
"""Order the layers: context, then global, then values the SDK derives."""
152+
"""Order the layers: per-call arguments, context, global, then SDK values.
153+
154+
``disable_geoip`` is the client setting, an SDK value. ``call_disable_geoip``
155+
is the argument of one call: it is a value of that event, so only the
156+
event's own ``$geoip_disable`` property beats it.
157+
"""
158+
call_properties = (
159+
{} if call_disable_geoip is None else {"$geoip_disable": call_disable_geoip}
160+
)
121161
# A value in the event, the context or super properties wins over every
122162
# value the SDK adds, including `$is_server` and `$geoip_disable`.
123163
sdk_properties = dict(system_properties or {})
@@ -129,6 +169,7 @@ def _build_event_defaults(
129169
sdk_properties["$geoip_disable"] = True
130170
return _EventDefaults(
131171
property_layers=(
172+
call_properties,
132173
context_properties or {},
133174
super_properties or {},
134175
sdk_properties,
@@ -242,10 +283,16 @@ def _to_v1_event(msg: dict) -> dict:
242283
if prop_key not in properties:
243284
continue
244285
# Always removed. A non-string value would fail the whole batch, so it
245-
# is dropped.
286+
# is dropped. None counts as unset and drops silently.
246287
value = properties.pop(prop_key)
247288
if isinstance(value, str):
248289
top_level[field_name] = value
290+
elif value is not None:
291+
log.warning(
292+
"dropping %s: a %s value is not a string",
293+
prop_key,
294+
_json_type_name(value),
295+
)
249296

250297
event = {
251298
"event": msg["event"],

0 commit comments

Comments
 (0)