Skip to content

feat!: send $lib and $lib_version in event properties - #1202

Merged
eli-r-ph merged 10 commits into
v1from
eli/v1-sdk-lib-per-event
Nov 9, 2026
Merged

eli-r-ph merged 10 commits into
v1from
eli/v1-sdk-lib-per-event

Conversation

@eli-r-ph

@eli-r-ph eli-r-ph commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

💡 Motivation and Context

v1 stripped $lib and $lib_version from properties. They now go on the wire as they are at send time, and the PostHog-Sdk-Info header is only a server fallback. After call properties, context tags and super_properties, the SDK fills its own pair: both when no layer sets a non-empty string $lib, only the version when $lib is posthog-python, otherwise nothing. before_send runs after and can change or remove it.

Only MCP analytics events from posthog.mcp.instrument() and PostHogMCP report posthog-python-mcp, set per event so it beats context tags and super_properties. The app's own events, headers and flag requests stay posthog-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 $lib rule in PostHog/sdk-specs#146, which replaces the spec's "SHALL NOT send $lib". docs/migration-7.x-to-8.0.md and 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

  • All commits are signed (see Commit signing)
  • I reviewed the submitted code.
  • I added tests to verify the changes.
  • I updated the docs if needed.
  • No breaking change or entry added to the changelog.

If releasing new changes

  • Ran sampo add to 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.py resolved by keeping both sides; the restored request helpers take float timeouts.

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.
@eli-r-ph eli-r-ph self-assigned this Nov 6, 2026
@eli-r-ph eli-r-ph changed the title fix: send $lib and $lib_version as SDK values on every event feat!: send $lib and $lib_version in event properties Nov 6, 2026
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
eli-r-ph marked this pull request as ready for review November 7, 2026 02:40
@eli-r-ph
eli-r-ph requested a review from a team as a code owner November 7, 2026 02:40
eli-r-ph and others added 4 commits November 6, 2026 18:47
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>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@marandaneto marandaneto left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
@veria-ai

veria-ai Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Reviews

@eli-r-ph
eli-r-ph merged commit 504e50d into v1 Nov 9, 2026
42 checks passed
@eli-r-ph
eli-r-ph deleted the eli/v1-sdk-lib-per-event branch November 9, 2026 23:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants