Repository navigation
posthog-v8.0.0
Major changes
- cacdb6f6 A
$session_idor$window_idthat 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.Nonecounts as unset and drops without a warning. An empty string is sent. In posthog-python 7.x.x these values were sent as properties. — Thanks @eli-r-ph! - cacdb6f6 Capture v1 is the only capture path. Events and AI events send to the capture v1 endpoints, and the legacy v0 capture path is removed. See the migration guide for breaking changes. — Thanks @eli-r-ph!
- cacdb6f6 The
$trace_idand$span_idthat the SDK takes from the active OpenTelemetry span now fill after the call'sproperties, context tags andsuper_properties, and beforebefore_send. A$trace_idor$span_idin a context tag orsuper_propertiesnow replaces the span's IDs, and setting either key stops the SDK adding both.AsyncPosthogfollows the same rules. — Thanks @eli-r-ph! - cacdb6f6
capture_exceptiontakes alevel=argument onClient,AsyncPosthogand the module, which sets$exception_level(default"error"). Reserved exception properties passed inproperties, such as$exception_listand$exception_level, are now ignored. In posthog-python 7.x.x they overrode the SDK's values with aDeprecationWarning.AsyncPosthog.capture_exceptionnow sends$exception_level. — Thanks @eli-r-ph! - cacdb6f6 The AI integrations no longer fall back to
capturefor a client object withoutcapture_ai. Creating an OpenAI, Anthropic or Gemini wrapper, the LangChainCallbackHandler, or the OpenAI Agents or Claude Agent SDK processor with such a client now logs one error and captures no AI events. Provider calls still work. The error shows up when you set the integration up, and not after a provider call. AClientorAsyncPosthoginstance, and the default global client, work as before. — Thanks @eli-r-ph! - cacdb6f6 Events send
$liband$lib_versionas they are at send time, whoever set them. If no$libis set in the call'sproperties, a context tag orsuper_properties, the SDK sets both toposthog-pythonand the installed version. If$libisposthog-pythonand$lib_versionis missing, the SDK fills in the version. A$libthat names another library is sent with whatever$lib_versionit has, so set both when you override them. Only a non-empty string counts as set. In posthog-python 7.x.x the SDK overwrote a$libor$lib_versionset in a call or a context tag.before_sendcan still change or remove both, andAsyncPosthogfollows the same rules. — Thanks @eli-r-ph! - cacdb6f6 An invalid event no longer costs the rest of its batch. An event with a missing, empty or non-string name, or with a non-string
distinct_idafterbefore_send, is dropped locally, an event that cannot be serialized is dropped alone (a non-finite float such asNaNis still sent asnull), and a property key JSON cannot represent is dropped from its event. The analytics per-event limit is now capture's 10 MiB request limit instead of 900 KiB. A personal API key (phx_...) disables the client like an empty key. The SDK's own log lines no longer include event content or invalid timestamp values.AsyncPosthogfollows the same rules. — Thanks @eli-r-ph! - cacdb6f6 A
disable_geoipargument to a call now counts as a value of that event. It wins over a$geoip_disablein context tags orsuper_properties, and a$geoip_disablein the call's ownpropertiesstill wins over it.disable_geoip=Falsenow sends$geoip_disable: false, so it turns GeoIP lookup on for that event even when a context tag orsuper_propertiesturns it off. The client'sdisable_geoipsetting keeps its place below every caller value.AsyncPosthogfollows the same rules. — Thanks @eli-r-ph! - cacdb6f6
group_identifyfalls back to the context distinct ID and then to$<group_type>_<group_key>instead of a random ID, and no longer adds the context session ID.alias()no longer takes its target from the context distinct ID. Context tags and options now apply toaliasandgroup_identify, but context tags, context options,super_optionsandsuper_propertiesdo not setprocess_person_profileon identify-style events ($identify,$create_alias,$merge_dangerously,$groupidentify,$setand$set_once) whose distinct ID the SDK did not generate. Those events default toTrueunless the call sets it. An empty or whitespace-onlydistinct_idcounts as missing, and generated personless distinct IDs are UUIDv7.AsyncPosthogfollows the same rules. — Thanks @eli-r-ph! - cacdb6f6 Capture follows a
307or308redirect only to the origin ofhost, at most 5 times, for the sync and async clients. Any other redirect fails the batch and reacheson_error. In posthog-python 7.x.x the sync client followed redirects to any origin and resent the event batch there. — Thanks @eli-r-ph! - cacdb6f6 The parameters after
pathinposthog.request.postand afterhostinposthog.request.flagsare keyword-only. Withgzipremoved, a posthog-python 7.x.x call that passed them by position bound them to the wrong parameter. It now raisesTypeError. — Thanks @eli-r-ph! - cacdb6f6 An invalid event
uuidis 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 stringuuidcounts as unset, so the SDK generates one without logging.AsyncPosthogfollows the same rules. — Thanks @eli-r-ph! - cacdb6f6 MCP instrumentation no longer relabels the whole client. In posthog-python 7.x.x,
posthog.mcp.instrument()andPostHogMCPchanged$libon every event the client sent, including the app's own, and the SDK name in its request headers, feature flag requests included.instrument()without a client relabeled the global client. Now only MCP analytics events reportposthog-python-mcp, and everything else reportsposthog-python. The label is set in each MCP event's own properties, so a$libinsuper_propertiesno longer replaces it.before_sendcan. — Thanks @eli-r-ph!
Minor changes
- cacdb6f6 MCP events take capture options. The
PostHogMCPcapture methods andMcpAnalytics.capturetake anevent_optionsargument, andMCPAnalyticsOptions(event_options=...)sets options on every eventinstrument()captures automatically, from a function of(request, extra)likeevent_properties. An event without an identity still always sendsprocess_person_profile: False.PostHogMCP.capture()keeps the core client'soptionsargument. — Thanks @eli-r-ph! - cacdb6f6
AsyncPosthog.capture_exceptionnow adds the active OpenTelemetry span's$trace_idand$span_id, likeClient.capture_exception, even whencapture_trace_contextis off. — Thanks @eli-r-ph! - cacdb6f6 The Celery integration propagates context options from the publisher to the worker, like tags. Options set with
set_context_optionbefore a task is published apply to every event captured while the task runs.propagate_context=Falsesends none of them. — Thanks @eli-r-ph! - cacdb6f6 AI integrations take capture options. Every wrapper method that takes
posthog_propertiesalso takesposthog_options(OpenAI, Anthropic, Gemini, sync and async, and the Claude Agent SDKquery()andPostHogClaudeSDKClient), and the Gemini clients take it as a default for every call. LangChain'sCallbackHandlerandPostHogMiddleware, andinstrument()and the tracing processors for OpenAI Agents and the Claude Agent SDK, takeoptions=. LangChain also readsposthog_optionsfrom run metadata. These options win over context options andsuper_options. An event without a distinct ID still always sendsprocess_person_profile: False, and a value that is not a dict is logged and ignored. — Thanks @eli-r-ph!
Patch changes
-
cacdb6f6 AI integrations (LLM wrappers, embeddings, LangChain and OpenAI Agents) treat an empty or whitespace-only
distinct_idas missing, as the client does: the event uses its trace or run ID and is personless. Before, an empty ID gave streaming calls, embeddings and LangChain the trace or run ID with person processing on, so PostHog created a person for each trace or run. Non-streaming wrapper calls used a random personless ID, and OpenAI Agents already treated an empty ID as missing. A whitespace-only ID was sent as given. — Thanks @eli-r-ph! -
cacdb6f6 Capture timestamps always have six fractional-second digits, even on a whole second:
2026-01-02T03:04:05.000000+00:00, not2026-01-02T03:04:05+00:00. This applies to the eventtimestamp, the batchcreated_atand thePostHog-Request-Timestampheader. Thetimestampthatbefore_sendreceives has the same format. — Thanks @eli-r-ph! -
cacdb6f6 Capture retry waits now vary randomly by up to 25%, so many clients do not retry at the same moment. — Thanks @eli-r-ph!
-
cacdb6f6 Capture retries
404and429responses like408and500,502,503,504, with the same backoff andRetry-Afterhandling. — Thanks @eli-r-ph! -
cacdb6f6 Capture makes one connection try per attempt, so every physical request carries its own attempt number and request timestamp. posthog-python 7.x.x also retried a failed connection up to twice inside each attempt, reusing the request timestamp, which shifted the events' stored time by the time spent connecting.
When
before_sendraises, the error line names the event and the exception type, not the exception message. The traceback is logged at debug level.Events without
NaNorInfinityare encoded once, without first copying them to replace non-finite numbers. Events that contain them still send those values asnull. — Thanks @eli-r-ph! -
cacdb6f6 Capture keeps the first event for each uuid in a request and drops the later copies.
on_errornow reports each dropped copy inCaptureError.dropsas(uuid, "duplicate_event_uuid"), and the SDK does not resend it. Each entry ofCaptureError.dropsis aCaptureDroppedEventfromposthog.capture_send, a tuple that also hasuuidanddetailsfields.verdict_summary()counts each drop by its own reason. — Thanks @eli-r-ph!