Skip to content

posthog-v8.0.0

Choose a tag to compare

@github-actions github-actions released this 17 Nov 19:40
Immutable release. Only release title and notes can be modified.
6edff41

Major changes

  • cacdb6f6 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 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_id and $span_id that the SDK takes from the active OpenTelemetry span now fill after the call's properties, context tags and super_properties, and before before_send. A $trace_id or $span_id in a context tag or super_properties now replaces the span's IDs, and setting either key stops the SDK adding both. AsyncPosthog follows the same rules. — Thanks @eli-r-ph!
  • cacdb6f6 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 posthog-python 7.x.x they overrode the SDK's values with a DeprecationWarning. AsyncPosthog.capture_exception now sends $exception_level. — Thanks @eli-r-ph!
  • cacdb6f6 The AI integrations no longer fall back to capture for a client object without capture_ai. Creating an OpenAI, Anthropic or Gemini wrapper, the LangChain CallbackHandler, 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. A Client or AsyncPosthog instance, and the default global client, work as before. — Thanks @eli-r-ph!
  • cacdb6f6 Events send $lib and $lib_version as they are at send time, whoever set them. If no $lib is set in the call's properties, a context tag or super_properties, the SDK sets both to posthog-python and the installed version. If $lib is posthog-python and $lib_version is missing, the SDK fills in the version. A $lib that names another library is sent with whatever $lib_version it 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 $lib or $lib_version set in a call or a context tag. before_send can still change or remove both, and AsyncPosthog follows 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_id after before_send, is dropped locally, an event that cannot be serialized is dropped alone (a non-finite float such as NaN is still sent as null), 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. AsyncPosthog follows the same rules. — Thanks @eli-r-ph!
  • cacdb6f6 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. — Thanks @eli-r-ph!
  • cacdb6f6 group_identify falls 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 to alias and group_identify, but context tags, context options, super_options and super_properties do not set process_person_profile on identify-style events ($identify, $create_alias, $merge_dangerously, $groupidentify, $set and $set_once) whose distinct ID the SDK did not generate. Those events default to True unless the call sets it. An empty or whitespace-only distinct_id counts as missing, and generated personless distinct IDs are UUIDv7. AsyncPosthog follows the same rules. — Thanks @eli-r-ph!
  • cacdb6f6 Capture follows a 307 or 308 redirect only to the origin of host, at most 5 times, for the sync and async clients. Any other redirect fails the batch and reaches on_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 path in posthog.request.post and after host in posthog.request.flags are keyword-only. With gzip removed, a posthog-python 7.x.x call that passed them by position bound them to the wrong parameter. It now raises TypeError. — Thanks @eli-r-ph!
  • cacdb6f6 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. — Thanks @eli-r-ph!
  • cacdb6f6 MCP instrumentation no longer relabels the whole client. In posthog-python 7.x.x, posthog.mcp.instrument() and PostHogMCP changed $lib on 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 report posthog-python-mcp, and everything else reports posthog-python. The label is set in each MCP event's own properties, so a $lib in super_properties no longer replaces it. before_send can. — Thanks @eli-r-ph!

Minor changes

  • cacdb6f6 MCP events take capture options. The PostHogMCP capture methods and McpAnalytics.capture take an event_options argument, and MCPAnalyticsOptions(event_options=...) sets options on every event instrument() captures automatically, from a function of (request, extra) like event_properties. An event without an identity still always sends process_person_profile: False. PostHogMCP.capture() keeps the core client's options argument. — Thanks @eli-r-ph!
  • cacdb6f6 AsyncPosthog.capture_exception now adds the active OpenTelemetry span's $trace_id and $span_id, like Client.capture_exception, even when capture_trace_context is 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_option before a task is published apply to every event captured while the task runs. propagate_context=False sends none of them. — Thanks @eli-r-ph!
  • cacdb6f6 AI integrations take capture options. Every wrapper method that takes posthog_properties also takes posthog_options (OpenAI, Anthropic, Gemini, sync and async, and the Claude Agent SDK query() and PostHogClaudeSDKClient), and the Gemini clients take it as a default for every call. LangChain's CallbackHandler and PostHogMiddleware, and instrument() and the tracing processors for OpenAI Agents and the Claude Agent SDK, take options=. LangChain also reads posthog_options from run metadata. These options win over context options and super_options. An event without a distinct ID still always sends process_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_id as 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, not 2026-01-02T03:04:05+00:00. This applies to the event timestamp, the batch created_at and the PostHog-Request-Timestamp header. The timestamp that before_send receives 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 404 and 429 responses like 408 and 500, 502, 503, 504, with the same backoff and Retry-After handling. — 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_send raises, the error line names the event and the exception type, not the exception message. The traceback is logged at debug level.

    Events without NaN or Infinity are encoded once, without first copying them to replace non-finite numbers. Events that contain them still send those values as null. — Thanks @eli-r-ph!

  • cacdb6f6 Capture keeps the first event for each uuid in a request and drops the later copies. on_error now reports each dropped copy in CaptureError.drops as (uuid, "duplicate_event_uuid"), and the SDK does not resend it. Each entry of CaptureError.drops is a CaptureDroppedEvent from posthog.capture_send, a tuple that also has uuid and details fields. verdict_summary() counts each drop by its own reason. — Thanks @eli-r-ph!