feat!: add option defaults; event values always win by eli-r-ph · Pull Request #359 · PostHog/posthog-go

eli-r-ph · 2026-10-07T01:06:52Z

💡 Motivation and Context

Stacked on #361.

In 1.x, DefaultEventProperties overwrote the event's own values, and there was no way to set options for every event or request.
This PR makes defaults fill only what the event left unset, on every message type.

Changes

Order: the event's values, then the request context, then client defaults, then SDK values.
BeforeSend sees every filled value and has the final say.
New Config.DefaultEventOptions and RequestContext.Options; a nil option counts as unset.
Defaults and request context now reach Exception, Identify, Alias and GroupIdentify.
Identify, Alias and GroupIdentify gain an EventProperties field.
The request context's session ID never fills GroupIdentify.
NewRequestContextMiddleware reads the X-PostHog-* headers only with WithCaptureTracingHeaders(true), because any client can set them.
$set, $set_once, $groups and $group_set merge one level deep.
The personless default is now a process_person_profile option that any layer can override.
posthogmcp gains ToolCall.Options and EventContext.Options and takes RequestContext.Options.
A caller-set $lib or $lib_version is removed before send.

💚 How did you test it?

Table tests cover each layer, each message type, and the BeforeSend view.
Middleware tests cover default, off and on for the tracing headers.
go vet, go test -race and make api-diff pass in all three modules.

🤖 Agent context

Autonomy: Human-driven (agent-assisted). Written with Claude Code.

🤖 Generated with Claude Code

eli-r-ph · 2026-10-07T20:00:11Z

@greptileai review

veria-ai · 2026-10-08T19:19:49Z

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 1 · PR risk: 0/10

dustinbyrne

I reproduced the four inline event-composition cases against this head and stack tip #368, using real SDK clients and a local recording server. The inlines include executed results, passing controls, base comparisons and suggested regression coverage.

AI-assisted review.

marandaneto

Automated advisory code review.

dustinbyrne

The composition fixes and regression coverage look good. Two non-blocking comments inline: preserving the spec/peer-aligned tracing-header default, and correcting the request-option scope in the migration guide.

AI-assisted review.

… defaults

…flag events

$mcp_unknown_tool, $mcp_input_required and $mcp_missing_capability now carry the process_person_profile option and RequestContext.Options, like tool calls.

Request-context properties and options, Config.DefaultEventProperties, Config.DefaultEventOptions and the personless process_person_profile option now fill in after BeforeSend, only for keys the event and the hook left unset. An option counts as unset when it is missing or nil; a property only when its key is missing. The request-context distinct ID still resolves before the hook. DefaultEventProperties and DefaultEventOptions now also reach Exception, Identify, Alias and GroupIdentify events, as event properties and options, never in $set or $group_set. DisableGeoIP no longer adds $geoip_disable to DefaultEventProperties. Every message already sets it before BeforeSend, and as a default it would come back after a hook removed it. A default $geoip_disable is still forced to true.

Request-context properties and options, Config.DefaultEventProperties, Config.DefaultEventOptions and the personless process_person_profile option now fill before BeforeSend, still only into keys the event left unset. BeforeSend sees every value and has the final say, including removing a default. $set, $set_once, $groups and $group_set fill one level deep when both values are maps. Capture.Groups merges into a $groups map key by key, and Identify and GroupIdentify Properties merge over a $set or $group_set in the event properties. Identify, Alias and GroupIdentify gain an EventProperties field for the event's own properties, which the defaults fill before the hook. It replaces the unexported default field. Hoisting still runs once, after the hook.

$is_server, $geoip_disable, system context and SendFeatureFlags properties now fill only keys the event, request context and DefaultEventProperties left unset, before BeforeSend. The SDK fills them last, so a DefaultEventProperties $geoip_disable: false wins over Config.DisableGeoIP. posthogmcp merges the sanitized request context under the call for every client and enqueues with an empty request context, so the client does not fill the unsanitized values again.

billing_limit_exceeded is a request-level 402 code. capture never puts it in a per-event drop result; the per-event tags are exceptions_over_quota, survey_responses_over_quota and llm_events_over_quota.

Capture sets both from the PostHog-Sdk-Info header and appends them after the event's keys, so a copy left in properties is a duplicate JSON key.

…racing headers are opt-in Request-context properties and options now fill Identify, Alias and GroupIdentify like Capture and Exception: below the event's own values, above the client defaults. The context session ID fills Identify and Alias but never GroupIdentify, whose distinct ID is not the session's person. Context ids never change an Identify or Alias. NewRequestContextMiddleware no longer reads the X-PostHog-Distinct-Id and X-PostHog-Session-Id headers unless WithCaptureTracingHeaders(true) is set, because any client can send them. Co-Authored-By: Claude Opus 5.5 <[email protected]>

…yed map - posthogmcp: a nil or typed-nil option no longer hides a legacy opt-out or erases a request-context option. - $set, $set_once, $groups and $group_set merge one level deep for any map with string keys, such as map[string]string. - A request-context $session_id set to nil now blocks a default session. Co-Authored-By: Claude Opus 5.5 <[email protected]>

…ons inherit Context and default properties now beat SDK-generated feature flag properties, matching the documented event > context > defaults > SDK order, and a nil child request-context option keeps the parent's value. Co-Authored-By: Claude Opus 5.5 <[email protected]>

eli-r-ph self-assigned this Oct 7, 2026

eli-r-ph force-pushed the v1-options-parity branch from 3078e55 to 9707868 Compare October 7, 2026 19:58

eli-r-ph changed the base branch from v1 to v1-sync-main October 7, 2026 19:58

eli-r-ph marked this pull request as ready for review October 7, 2026 20:44

eli-r-ph requested a review from a team as a code owner October 7, 2026 20:44

eli-r-ph force-pushed the v1-options-parity branch from cd9063c to 3cf4f49 Compare October 7, 2026 22:21

veria-ai Bot reviewed Oct 8, 2026

View reviewed changes

Comment thread posthog.go Outdated

eli-r-ph force-pushed the v1-options-parity branch 2 times, most recently from bad06b9 to 84df98b Compare October 9, 2026 18:28

eli-r-ph force-pushed the v1-sync-main branch from 75b05e5 to cc10078 Compare October 9, 2026 18:28

eli-r-ph mentioned this pull request Oct 10, 2026

fix!: match capture v1 rules for ids, timestamps and size #367

Merged

eli-r-ph force-pushed the v1-sync-main branch from cc10078 to 84395b0 Compare October 11, 2026 20:03

eli-r-ph force-pushed the v1-options-parity branch from c36473b to 487b20b Compare October 11, 2026 20:03

eli-r-ph changed the title ~~feat!: add default and request-context options; event values win over defaults~~ feat!: add option defaults; event values always win Oct 13, 2026

Base automatically changed from v1-sync-main to v1 October 18, 2026 17:47

eli-r-ph force-pushed the v1-options-parity branch from d0ac310 to 7e1e113 Compare October 18, 2026 17:52

dustinbyrne reviewed Oct 20, 2026

View reviewed changes

Comment thread posthogmcp/event.go Outdated

Comment thread posthogmcp/analytics.go

Comment thread properties.go

Comment thread request_context.go

dustinbyrne requested a review from a team October 20, 2026 02:47

marandaneto reviewed Oct 21, 2026

View reviewed changes

Comment thread posthog.go Outdated

Comment thread request_context.go

marandaneto requested a review from a team October 21, 2026 12:53

dustinbyrne approved these changes Oct 21, 2026

View reviewed changes

Comment thread request_context.go

Comment thread docs/migration-v2.md

dustinbyrne reviewed Oct 21, 2026

View reviewed changes

Comment thread request_context.go

feat!: add default and request-context options; event values win over…

bb145ed

… defaults

eli-r-ph and others added 15 commits October 21, 2026 17:43

feat: add ToolCall.Options; keep legacy option properties on minimal …

ce0102c

…flag events

chore: update public API snapshot for options fields

f399553

fix: send the person profile option on MCP optional events

09fee6d

$mcp_unknown_tool, $mcp_input_required and $mcp_missing_capability now carry the process_person_profile option and RequestContext.Options, like tool calls.

feat: add EventContext.Options to the optional MCP events

b76fba8

chore: update public API snapshot for unexported default fields

1970380

fix: resolve the request-context session ID before BeforeSend

4bc3e44

fix: fill MCP request context after BeforeSend, defaults in callbacks

fee5806

test: use real per-event quota tags in drop fixtures

231f490

billing_limit_exceeded is a request-level 402 code. capture never puts it in a per-event drop result; the per-event tags are exceptions_over_quota, survey_responses_over_quota and llm_events_over_quota.

fix: strip caller-set $lib and $lib_version before send

7f5328f

Capture sets both from the PostHog-Sdk-Info header and appends them after the event's keys, so a copy left in properties is a duplicate JSON key.

eli-r-ph force-pushed the v1-options-parity branch from ab9768c to c900f09 Compare October 22, 2026 02:11

eli-r-ph merged commit 5172221 into v1 Oct 22, 2026
32 checks passed

eli-r-ph deleted the v1-options-parity branch October 22, 2026 14:59

eli-r-ph mentioned this pull request Oct 22, 2026

fix!: read tracing headers by default in the request context middleware #386

Merged

Navigation Menu

Repository navigation

feat!: add option defaults; event values always win - #359

feat!: add option defaults; event values always win#359
eli-r-ph merged 16 commits into
v1from
v1-options-parity

eli-r-ph commented Oct 7, 2026 •

edited

Loading

Uh oh!

eli-r-ph commented Oct 7, 2026

Uh oh!

Uh oh!

veria-ai Bot commented Oct 8, 2026 •

edited

Loading

Uh oh!

dustinbyrne left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marandaneto left a comment

Uh oh!

Uh oh!

Uh oh!

dustinbyrne left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

eli-r-ph commented Oct 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💡 Motivation and Context

Changes

💚 How did you test it?

🤖 Agent context

Uh oh!

eli-r-ph commented Oct 7, 2026

Uh oh!

Uh oh!

veria-ai Bot commented Oct 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR overview

Security review

Uh oh!

dustinbyrne left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marandaneto left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dustinbyrne left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

eli-r-ph commented Oct 7, 2026 •

edited

Loading

veria-ai Bot commented Oct 8, 2026 •

edited

Loading