You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4d32397
Browse filesBrowse the repository at this point in the historyBrowse files
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.
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.
`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`.
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.
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`.
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.
Copy file name to clipboardExpand all lines: docs/migration-7.x-to-8.0.md
+14-5Lines changed: 14 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,8 @@ Read the checklist first, then the sections that apply to you.
9
9
You need to change code if your app does any of these:
10
10
11
11
- 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=...)`
12
14
- sets `capture_mode`, `POSTHOG_CAPTURE_MODE` or `gzip`
13
15
- imports `CaptureV1Error`, `posthog.capture_v1`, `request.batch_post`, `EVENTS_ENDPOINT` or `AI_EVENTS_ENDPOINT`
14
16
- 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
58
60
|`CaptureV1Error` (`from posthog.capture_v1 import CaptureV1Error`) |`CaptureError` (`from posthog import CaptureError`). There is no alias. |
59
61
|`posthog.capture_v1`|`posthog.capture_event` and `posthog.capture_send`|
60
62
|`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`. |
62
64
| The `backoff` dependency | Add it to your own requirements if your code imports it. |
63
65
64
66
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
100
102
101
103
- 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.
102
104
- 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.
104
106
- Generated uuids are UUIDv7.
105
107
106
108
## Session and window IDs
@@ -110,7 +112,13 @@ The SDK moves them out of `properties` for you.
110
112
111
113
- A string is sent as given, including `""`.
112
114
-`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`.
114
122
115
123
## Event options
116
124
@@ -141,10 +149,10 @@ Capture v1 sends processing options in an `options` object, next to `properties`
141
149
142
150
Values apply in this order. Steps 2 to 4 fill only the options and properties that the steps before them left unset:
143
151
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`
145
153
2. context options and tags
146
154
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`
148
156
5.`before_send`, which sees the result of steps 1 to 4 and can change or remove any of it
149
157
6. legacy properties, which fill unset options and are then removed
150
158
@@ -157,6 +165,7 @@ These changes follow from this order:
157
165
158
166
- Properties passed to a call now override `super_properties`. `super_properties` can no longer change `$lib` or `$lib_version`.
159
167
- 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.
160
169
- 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.
161
170
- 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.
162
171
- 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.
Copy file name to clipboardExpand all lines: posthog/__init__.py
+7-3Lines changed: 7 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -786,17 +786,21 @@ def alias(
786
786
787
787
defcapture_exception(
788
788
exception: Optional[ExceptionArg] =None,
789
+
*,
790
+
level: Optional[str] =None,
789
791
**kwargs: Unpack[OptionalCaptureArgs],
790
792
) ->Optional[str]:
791
793
"""
792
794
Capture exceptions that happen in your code.
793
795
794
796
Args:
795
797
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.
796
800
**kwargs: Optional capture arguments including distinct_id, properties,
797
801
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.
800
804
801
805
Details:
802
806
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`.
0 commit comments