Repository navigation
feat!: send $lib and $lib_version in event properties - #1202
Merged
Merged
Conversation
Events now carry $lib and $lib_version on the wire as they are at send time. The SDK fills its own identity last, as a pair: with no $lib set it fills both, and with $lib naming this SDK and no $lib_version it fills the version. Only a non-empty string counts as set. A $lib naming another library keeps whatever $lib_version it has. before_send still runs after the fill and has the last word.
This reverts commit 331ae32 (#1034), except its migration guide and MCP README edits, which follow in a separate docs change. - posthog/client.py: kept v1's metrics autocapture and emails methods and put _set_library_identity and _request_identity_kwargs after them. - posthog/request.py: the restored _remote_config and _get take float timeouts, like the public remote_config and get they back. - The relabeled identity is an integration label on events: it fills $lib and $lib_version as a pair above context tags and super_properties when the event sets no $lib.
Reverts the whole-client relabel from 4ed5c13. MCP events get the posthog-python-mcp pair in the MCP event builder, before before_send, by the same pair rule as the SDK fill. The client's other events, its PostHog-Sdk-Info header and its flag requests keep posthog-python, and instrument() without a client no longer relabels the global client. Works the same for Client, AsyncClient and PostHogMCP.
eli-r-ph
marked this pull request as ready for review
November 7, 2026 02:40
Say every event carries the SDK pair by default, not always, and that the version fill applies when $lib is set without $lib_version. Explain that the MCP label is set in each MCP event's own properties, so context tags and super_properties don't replace it, which the checklist bullet now points at. Drop "fills them last" (before_send runs after the fill) and name 7.x's relabelled request headers generically.
Add whitespace $lib (counts as set), a non-string version on the SDK's own $lib (replaced), and a non-string $lib from super_properties to the sync and async tables. On MCP events, cover a number $lib, $lib set to posthog-python (the client fills its version) and the label beating a context tag as well as super_properties.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3 of 13 tasks
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5 of 6 tasks
marandaneto
approved these changes
Nov 9, 2026
marandaneto
left a comment
Member
There was a problem hiding this comment.
The code looks good; no qualifying findings. Verdict: correct.
* feat(mcp): add event_options to MCP capture calls and instrument The PostHogMCP capture_* methods and McpAnalytics.capture take a keyword-only event_options argument, and MCPAnalyticsOptions gains an event_options callback, called for the same events as event_properties. Per-call options win over the callback's key by key, and an event without an identity still always sends process_person_profile: False. A non-dict value is logged and ignored. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(mcp): document MCP event_options Covers the per-call argument and the callback, why context options set inside a tool handler miss $mcp_tool_call, copying options in MCP before_send, and the options vs event_options split on PostHogMCP. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(celery): propagate context options to workers (#1207) * feat(celery): propagate context options to workers Publish context options in an X-POSTHOG-CONTEXT-OPTIONS task header, next to the tags header, and set them as context options on the worker before the task started event. propagate_context=False sends none. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(celery): point eager tasks to explicit PostHog headers Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(ai): take capture options in the AI integrations (#1208) * feat(ai): take capture options in the AI integrations Every AI wrapper method that takes posthog_properties also takes posthog_options, and the Gemini clients take it as a per-client default. LangChain's CallbackHandler and PostHogMiddleware, and the OpenAI Agents and Claude Agent SDK instrument() and processors, take options=. LangChain also reads posthog_options from run metadata. The wrappers never pass posthog_options to the provider. The options are sent as the event's own options, below the personless process_person_profile: False. A value that is not a dict is logged and ignored, and no options argument is passed when none are set. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(ai): send LangChain exception events with the run's options Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(migration): simplify the 8.0 checklist and MCP hook note Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(ai): pass exception options as a typed keyword Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
💡 Motivation and Context
v1 stripped
$liband$lib_versionfrom properties. They now go on the wire as they are at send time, and thePostHog-Sdk-Infoheader is only a server fallback. After call properties, context tags andsuper_properties, the SDK fills its own pair: both when no layer sets a non-empty string$lib, only the version when$libisposthog-python, otherwise nothing.before_sendruns after and can change or remove it.Only MCP analytics events from
posthog.mcp.instrument()andPostHogMCPreportposthog-python-mcp, set per event so it beats context tags andsuper_properties. The app's own events, headers and flag requests stayposthog-python.Do not merge or release until PostHog stores the event's
$lib: PostHog/posthog#130587, plus the splice switch in PostHog/posthog#130592 turned off in every environment.Matches the
$librule in PostHog/sdk-specs#146, which replaces the spec's "SHALL NOT send$lib".docs/migration-7.x-to-8.0.mdand the MCP README cover the new rule.💚 How did you test it?
Sync and async wire tests for the pair rule,
before_send, minimized events and MCP, plus updated snapshots. pytest, ruff, mypy and the public API and strict type checks pass locally, except three fork tests that also fail on macOS without this change.📝 Checklist
If releasing new changes
sampo addto generate a changeset file (major changeset written by hand)🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Cursor, Claude Opus 5.5. Revert conflicts in
client.pyresolved by keeping both sides; the restored request helpers take float timeouts.