Skip to content

feat!: send events through capture v1 and add captureAi - #881

Merged
turnipdabeets merged 72 commits into
chore/v4-remove-deprecatedfrom
feat/v4-capture-v1
Nov 5, 2026
Merged

turnipdabeets merged 72 commits into
chore/v4-remove-deprecatedfrom
feat/v4-capture-v1

Conversation

@turnipdabeets

@turnipdabeets turnipdabeets commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #871 (chore/v4-remove-deprecated).

💡 Motivation and Context

Moves capture to capture v1 for posthog-android 4.0: analytics events go to POST /i/v1/analytics/events and the new captureAi(...) sends AI events to POST /i/v1/ai/events. This matches posthog-ios 4.0 (PostHog/posthog-ios#938) and the posthog-python 8.0, posthog-go 2.0 and posthog-rs 1.0 v1 releases and their AI lanes, and Ingestion's goal of moving the mobile SDKs to the v1 endpoints with captureAi in every v1 release. Flutter and React Native need captureAi on both natives before they can expose it.

This PR now contains the whole capture v1 stack. Merged into it:

From the release review, directly on this branch:

  • PostHogEvent.options is a property, not a constructor parameter, so the PostHogEvent constructor and copy keep their 3.x signatures. posthog-server is a minor release and its beforeSend gets PostHogEvent, so the old trailing parameter broke Java callers and copy calls compiled against 3.x. When beforeSend returns a different event whose options are null, such as a copy, it keeps the options of the event the hook was given.
  • Guide gaps: internal TODO comments removed, RRStyle listed, captureAi returns null for an empty name, per-event quota drops, self-hosting the AI path, whitespace-only tokens, the 3.x $set replacement rule.

Transport

  • Authorization: Bearer <projectToken> plus PostHog-Sdk-Info (<sdkName>/<sdkVersion>, which Flutter, React Native and KMP already set), PostHog-Attempt, PostHog-Request-Id and PostHog-Request-Timestamp. The body is {created_at, batch}, with no api_key or sent_at.
  • $session_id/$window_id move to the event root, and $lib/$lib_version are no longer sent as properties (the server reads them from PostHog-Sdk-Info). A string session/window ID, including "", is sent unchanged; a non-string is dropped with a debug log naming the key and JSON type; null drops silently.
  • The server's per-event results are applied: ok/warning/drop events leave the queue, only retry events are resent, and the response Retry-After is honored for that resend. The queue resends exactly the events of a request that failed or came back with events to retry, before newer ones, so the retry keeps its request ID and created_at and increments the attempt. Retry identity is kept per endpoint, so the analytics and AI lanes don't reset each other's attempt numbers. A 413 halving is a new request. Events missing from the results count as delivered: a resend would duplicate stored events. A 2xx whose results can't be read (malformed body, missing or non-object results, a transfer that failed after the status, or a response over 1 MiB) fails the whole batch without a retry, as the spec's FC-6a requires.
  • Network errors and 404, 408, 429, 500, 502, 503 and 504 are retried (fix: retry capture v1 requests that get 404 or 429 #897, following fix: retry capture requests that get 404 or 429 posthog-go#395: drop events only when they can never be delivered or the buffer is full). 3xx and other statuses are terminal. 413 keeps halving the batch.
  • No /batch fallback: a host that doesn't serve the v1 route keeps the events queued (404 is retried) until it does. PostHogApi.batch() stays only for posthog-server, which keeps /batch until its own major. Events cached by pre-3.0 versions (PostHogSendCachedEventsIntegration) and 3.x events still queued on disk are sent through v1 too.
  • Retry-After (delay-seconds or an HTTP-date) is honored as a floor, capped at 30 seconds, and the backoff doubles from 1 s to 30 s with ±25% jitter kept in milliseconds. Both apply to every queue (events, replay, logs).
  • Capture follows only 307/308 redirects to the same origin as host, at most 5 hops, re-sending body and headers. Other redirects are terminal. OkHttp would otherwise follow any 3xx, drop Authorization cross-host and turn a 302 into a GET, so automatic redirects are off for the capture client. So is retryOnConnectionFailure: an OkHttp resend would repeat the attempt number and timestamp.
  • Requests carry at most maxBatchSize events and about 5 MiB (checked before appending; an event larger than that is sent on its own), and the queue sends as soon as that much is queued, for analytics and AI.
  • With debug on, drop/retry logging is one line per batch: dropped events counted by the server's details tag (cleaned and clipped, most common first, e.g. misrouted_event, ai_event_too_big), duplicate copies dropped and events to retry. Never per event, and no uuids, names or payloads. Debug logs name the event count and response status, never request or response bodies.

Per-event options (new public API)

  • options: Map<String, Any?>? = null as the last parameter of capture, screen, identify, setPersonProperties, alias, group and captureException on PostHogInterface, PostHog and the PostHog companion, and a PostHogEvent.options property (persisted in the queue, editable in beforeSend; not a constructor parameter, so the constructor and copy are unchanged). For identify the options apply to the $identify or $set event it sends; for group to $groupidentify; for alias to $create_alias.
  • Known keys: process_person_profile, cookieless_mode, disable_skew_correction and product_tour_id. Any other key is sent as-is; values are never coerced (the server parses them leniently).
  • The legacy $process_person_profile, $cookieless_mode, $ignore_sent_at and $product_tour_id properties are converted when the request is built, after beforeSend. Each is always removed from properties and only fills an option that is unset or null.
  • Precedence, lowest first: legacy property, SDK default, caller option, beforeSend. An option set to null counts as unset.
  • The SDK sets process_person_profile: false only when person processing is off (personProfiles = NEVER, or IDENTIFIED_ONLY before identify), and no longer writes a $process_person_profile property on every event. A null legacy value keeps the personless default.
  • The 3-arg identify moved from PostHogCoreInterface to PostHogStatelessInterface; PostHogInterface has the 4-arg one.

Property precedence (PostHog/sdk-specs#143)

  • Properties the SDK sets itself (context, SDK info, feature flags, $screen_name, session id, $is_identified, replay debug values) → registered super properties → the properties passed to the call (userProperties, userPropertiesSetOnce and groups are per-call values) → beforeSend. In 3.x the SDK's values beat super properties, and $is_identified, $process_person_profile and the replay debug values also beat caller properties.
  • A blank caller $screen_name, $session_id or distinct_id still replaces the SDK's value, as in 3.x.

captureAi (new public API)

  • captureAi takes the same arguments as capture (including options) and goes through the same enrichment, precedence, personless default and beforeSend. Only the queue differs. capture never reroutes $ai_* events; a captureAi name that doesn't start with $ai_ logs a debug line and is sent unchanged (the server reports misrouted_event).
  • AI events go to their own disk queue (posthog-disk-ai-queue, PostHogConfig.aiStoragePrefix) with its own executor and retry state, created at setup so events left on disk by a previous launch still send, and flushed by flush() and close(). A failing or slow AI lane never delays or drops analytics events.
  • captureAi returns the queued event's uuid, or null when the event isn't queued: disabled, opted out, an empty name, dropped by beforeSend, or over the size limit.
  • A serialized AI event over captureAiMaxEventBytes, measured before encryption, is dropped in captureAi, which logs (debug) only the event name and the limit. The AI queue keeps at most captureAiMaxQueueSize events and 50 MiB on disk, dropping the oldest first.
  • New PostHogConfig settings, named after the server SDKs': captureAiCompression (gzip), captureAiMaxQueueSize (100), captureAiTimeout (60 s read/write idle timeouts on a derived OkHttp client), captureAiMaxEventBytes (8 MiB + 64 KiB for the whole serialized event: PostHog's 8 MiB properties limit plus room for the rest; it can only lower, and a larger value logs a debug line). Non-positive values fall back to the defaults.

Other changes in the stack

  • maxRetries is renamed pushNotificationSubscriptionMaxRetries (no alias): it only limits push-subscription retries. Event, replay and log retries have no limit, as before.
  • A projectToken starting with phx_ (a personal API key) disables the SDK at setup, like an empty token. posthog-server inherits this through PostHogStateless.setup, so it gets its own minor changeset.
  • An empty or whitespace-only distinctId argument to capture uses the current distinct ID instead of dropping the event.
  • An event beforeSend returns keeps the uuid of the capture it came from, so a hook that returns a cached earlier event can't repeat a uuid.
  • A $set/$identify sent with process_person_profile: false neither stores nor matches the person-properties dedup hash.
  • The minimal $feature_flag_called event also keeps $cookieless_mode, $ignore_sent_at and $product_tour_id, so they survive until they are converted to options.
  • Deep Link Opened skips query parameters whose name starts with $, so a link can't set a PostHog property such as $process_person_profile.
  • An unserializable property is logged by key and type, never by value. A nested map with a non-string key keeps the event: scalar keys are converted to strings and other keys are dropped.
  • beforeSend gets its own copy of nested maps, lists and arrays, so a hook can't change the caller's values; no copy is made without a hook. A hook that throws drops only its event and logs (debug) the event name and exception type, never the message.
  • Compliance adapter: advertises capture_v1, capture_ai_v1, encoding_gzip, event_options, generated_payloads, log_capture, property_layers and fail_open; tracks both v1 routes; forwards options and timestamp; runs with personProfiles = ALWAYS like a server SDK. The workflow pins harness 1.26.0 and also runs for PRs into chore/v4-*/feat/v4-*.
  • docs/migration-3.x-to-4.0.md and the 4.0 changeset bullets.

Breaking changes

Change Who notices
Endpoint moves to /i/v1/analytics/events with Bearer auth; no /batch fallback Reverse proxies, allowlists, WAF rules and self-hosted instances must serve the new path. A 404 keeps events queued; a 403/405 drops them.
Capture sends Authorization: Bearer, replacing a custom Authorization from requestHeaders Proxies that authenticate with Authorization need another header
3xx is terminal, 404 is retried; Retry-After capped at 30 s; jittered backoff Redirecting or rate-limited setups; log-based expectations on retry timing
Only same-origin 307/308 redirects are followed host pointing at something that redirects elsewhere
Legacy option properties are sent as options; the server drops events with unreadable values Apps that set these properties to odd values
New trailing options parameter on seven PostHogInterface methods, new captureAi Java callers (pass null), anything implementing PostHogInterface
PostHogCoreInterface.identify moved to PostHogStatelessInterface / PostHogInterface Code that holds a PostHogCoreInterface reference and calls identify
Super and event properties override SDK-set properties, including $is_identified, $process_person_profile and replay debug values Apps that register or pass those keys and expected the SDK's value
$process_person_profile is sent only when person processing is off, as an option Filters on $process_person_profile = true
beforeSend can't change an event's uuid; $-prefixed deep link parameters are skipped Hooks that set uuids; links that set PostHog properties
maxRetries → pushNotificationSubscriptionMaxRetries; phx_ tokens disable the SDK Apps that set it; misconfigured apps (they got 401s before)

All of these are in .changeset/android-v4-major.md (plus .changeset/server-keep-on-feature-flags.md) and in docs/migration-3.x-to-4.0.md.

Differences from the spec and the other v1 SDKs (same as posthog-ios 4.0 unless noted)

  • No retry limit: events stay in the persisted queue bounded by maxQueueSize. Server SDKs give up after 4 attempts.
  • 413 halves the batch until a single oversized event is dropped (proxies often cap below 10 MiB).
  • Backoff starts at 1 s, not 100 ms, with jitter in milliseconds.
  • Gzip on by default, for analytics (compression) and AI (captureAiCompression).
  • No global or context options. A registered legacy $ key becomes its option at send time.
  • A caller or registered legacy $process_person_profile suppresses the SDK's personless option instead of losing to it.
  • process_person_profile: false goes in options, not properties. capture/spec.md "Caller can't override person-processing state" expects the property; the compliance adapter runs with personProfiles = ALWAYS.
  • beforeSend can't change the uuid. The sdk-specs before-send-hook spec lets a hook change it. Android replaces it with the capture's own uuid, so a hook that returns an event kept from an earlier call can't repeat a uuid in a batch.
  • An empty distinct ID set in beforeSend is sent, and PostHog drops the event. The blank-ID fallback runs before the hooks; docs(capture): specify capture v1 delivery for every v1 SDK sdk-specs#146 says the SDK should treat an empty ID as missing.
  • captureAi (the capture-ai spec covers server SDKs): no uuid argument, like Android capture, but it returns the uuid; oversize events are dropped at the call; the queue is created at setup, not lazily; the queue limit is 100 events and 50 MiB, not 1000 events.

💚 How did you test it?

  • New suites cover the stack:
    • PostHogCaptureV1Test: the wire format and headers, $lib strip, session/window lift, legacy-property hoisting and precedence, per-event results and the kept retry set, retry identity, status classification (404 and 429 retried), redirects, 2xx with unreadable results or a failed transfer, Retry-After on a 2xx, the AI path and the per-event drop log.
    • PostHogQueueTest, PostHogQueueDurabilityTest: partial retention, jitter bounds, the 30 s Retry-After cap, the partial-retry Retry-After floor, and a fatal event sent while a request waits to be retried.
    • PostHogCaptureOptionsTest: options reaching PostHogEvent.options for every method, beforeSend edits, the personless option under each personProfiles mode, precedence, the blank-distinctId fallback, the dedup hash with a personless $set (including lenient false values such as "false" and 0), the allowlist and uuid stability.
    • PostHogCaptureAiTest: routing, beforeSend and options, 404 retried, oversize events dropped when queued, splitting at the byte limit, flushing once a batch's worth of bytes is queued, the return value, per-lane timeout and compression, separate retry identity, flush()/close() draining the AI queue, an event with exactly 8 MiB of properties.
    • PostHogQueueByteLimitsTest: byte accounting on add/load/remove (including a file deleted from disk), eviction of the oldest, check-before-append windows, an oversize record alone.
    • PostHogSendCachedLegacyEventsIntegrationTest: the legacy queue on v1.
  • The Android event-shape snapshot was re-recorded on purpose (v1 envelope, options, no $lib or $process_person_profile).
  • After merging feat!: add captureAi on the capture v1 AI endpoint #884 and feat!: add per-event capture options and one property precedence #882 and the latest chore/v4-remove-deprecated (chore!: pass the load result to the feature flags callback #877 conflicted only in the changeset): ./gradlew apiCheck spotlessCheck :posthog:test :posthog-android:testReleaseUnitTest :posthog-server:test pass locally. The compliance adapter compiles.
  • New tests for the last review round were checked against the old code: each fails without its fix.
  • Compliance harness 1.26.0 in CI on d6a416a: 232/232 (capture_v1 105/105, capture_ai_v1 110/110, feature_flags 17/17).
  • CI passed on feat!: add captureAi on the capture v1 AI endpoint #884 (Build Job, compliance) before it was merged.
  • Device run against PostHog Cloud (US), sample app on an API 37 emulator, with this PR, feat!: posthog-android 4.0 and posthog 7.0 #871, fix(flags): decode payloads cached by 3.x from the cached flag details #935 and main merged together:
    • 3.75.3 → 4.0 upgrade: 21 events queued offline by 3.x were sent through /i/v1/analytics/events (HTTP 200) after the upgrade, along with 3.x-queued replay snapshots.
    • Every event-sending method, options, a custom timestamp, NaN/infinite values (dropped, event kept), non-string map keys, a 300 KB property and the precedence order (super < event < beforeSend, a caller $os over the SDK's) arrived as expected. An empty name was dropped locally.
    • captureAi sent to /i/v1/ai/events (HTTP 200) and the trace shows up with a 2 MB input stored as a blob; a 9 MiB event returned null.
    • A burst of 300 events: 300 stored, no duplicates; a DNS failure after reconnect was retried without loss.
  • Not done: captureAi docs on posthog.com / LLM analytics.

📝 Checklist

  • All commits are signed
  • 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 pnpm changeset to generate a changeset file (bullets added to .changeset/android-v4-major.md, plus .changeset/server-keep-on-feature-flags.md)

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Built with Claude Code. Subagents implemented the transport, options and AI lane against the capture v1 server contract, the harness capture_v1/capture_ai_v1 contracts, sdk-specs#143, the sdk-specs capture-ai spec and the posthog-ios 4.0 branch; review cycles on each PR of the stack fed fixes back. #884 and #882 were squash-merged into this branch after approval.

Maintainer decisions: no /batch fallback from the start (iOS added and then removed one); keep PostHogApi.batch() for posthog-server; keep unlimited retries and 413 halving as mobile divergences; retry 404 and 429 (posthog-go#395); add a public options API in 4.0 and move identify off PostHogCoreInterface rather than carry two overloads; keep the uuid pin client-only; a separate AI lane with a small disk queue, config named after the server SDKs.

TODO before release

🤖 Generated with Claude Code

@turnipdabeets turnipdabeets self-assigned this Oct 24, 2026

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

PostHog Review · Standard · reviewed 71d07c1: 2 Must fix, 2 Should fix.

This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

posthog-android Compliance Report

Date: 2026-11-04T23:11:43.006889+00:00
Duration: 472612ms

✅ All Tests Passed!

232/232 tests passed


Capture_V1 Tests

✅ 105/105 tests passed

View Details
Test Status Duration
Endpoint And Method.Targets V1 Endpoint ✅ 309ms
Endpoint And Method.Does Not Use Legacy Endpoints ✅ 34ms
Required Headers.Has Authorization Bearer Header ✅ 24ms
Required Headers.Has Content Type Json ✅ 24ms
Required Headers.Has Posthog Sdk Info Format ✅ 20ms
Required Headers.Has Posthog Attempt Header ✅ 22ms
Required Headers.Has Posthog Request Id ✅ 19ms
Required Headers.Has Posthog Request Timestamp ✅ 22ms
Required Headers.Has User Agent ✅ 18ms
Body Format.Body Has Created At And Batch ✅ 21ms
Body Format.No Api Key In Body ✅ 18ms
Body Format.No Sent At In Body ✅ 19ms
Event Format.Event Has Required Root Fields ✅ 18ms
Event Format.Event Uuid Is Valid ✅ 18ms
Event Format.Event Timestamp Is Rfc3339 ✅ 17ms
Event Format.Non Utc Event Timestamp Is Converted To Utc ✅ 18ms
Event Format.Distinct Id Is String ✅ 16ms
Event Format.Distinct Id At Root Not Properties ✅ 19ms
Event Format.Custom Properties Preserved ✅ 20ms
Event Format.Set Properties Preserved ✅ 21ms
Event Format.Set Once Properties Preserved ✅ 17ms
Event Format.Groups Properties Preserved ✅ 19ms
Event Format.Sdk Generates Uuid If Not Provided ✅ 21ms
Event Format.Event Has Required Root Fields Batch ✅ 26ms
Event Format.Event Uuid Is Valid Batch ✅ 23ms
Event Format.Event Timestamp Is Rfc3339 Batch ✅ 23ms
Event Format.Distinct Id Is String Batch ✅ 22ms
Event Format.Distinct Id At Root Not Properties Batch ✅ 20ms
Event Format.Custom Properties Preserved Batch ✅ 23ms
Event Format.Set Properties Preserved Batch ✅ 22ms
Event Format.Set Once Properties Preserved Batch ✅ 21ms
Event Format.Groups Properties Preserved Batch ✅ 23ms
Event Format.Sdk Generates Uuid If Not Provided Batch ✅ 22ms
Batch Behavior.Multiple Events In Single Batch ✅ 28ms
Batch Behavior.Batch Envelope Smoke ✅ 25ms
Batch Behavior.Flush With No Events Sends Nothing ✅ 14ms
Batch Behavior.Flush At Triggers Batch ✅ 1014ms
Batch Behavior.Created At Reflects Batch Creation Time ✅ 22ms
Deduplication.Generates Unique Uuids ✅ 38ms
Deduplication.Different Events Same Content Different Uuids ✅ 16ms
Deduplication.Preserves Uuid On Retry ✅ 7014ms
Deduplication.Preserves Timestamp On Retry ✅ 7019ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 7027ms
Deduplication.No Duplicate Events In Batch ✅ 34ms
Header Behavior On Retry.Attempt Header Starts At One ✅ 16ms
Header Behavior On Retry.Attempt Header Increments On Retry ✅ 12024ms
Header Behavior On Retry.Request Id Preserved On Retry ✅ 7019ms
Header Behavior On Retry.Different Requests Have Different Request Ids ✅ 2031ms
Header Behavior On Retry.Request Timestamp Changes On Retry ✅ 7019ms
Response Format Validation.Success Response Has Uuid Keyed Results ✅ 18ms
Response Format Validation.Success Response Has Ok For Each Event ✅ 19ms
Response Format Validation.Success No Retry After When All Ok ✅ 17ms
Response Format Validation.Success Retry After Present When Retry Events ✅ 2009ms
Response Format Validation.Success No Retry After When Drop Only ✅ 20ms
Response Format Validation.Response Echoes Request Id ✅ 13ms
Retry Behavior.Retries On 408 ✅ 7014ms
Retry Behavior.Retries On 500 ✅ 7018ms
Retry Behavior.Retries On 503 ✅ 7022ms
Retry Behavior.Retries On 504 ✅ 7017ms
Retry Behavior.Retries On 404 ✅ 6019ms
Retry Behavior.Retries On 429 ✅ 6015ms
Retry Behavior.Retries On 502 ✅ 7018ms
Retry Behavior.Retryable Errors Have Retry After ✅ 4015ms
Retry Behavior.Respects Retry After On Retryable Error ✅ 10025ms
Retry Behavior.Does Not Retry On 400 ✅ 4020ms
Retry Behavior.Does Not Retry On 401 ✅ 4020ms
Retry Behavior.Does Not Retry On 402 ✅ 4019ms
Retry Behavior.Does Not Retry On 413 ✅ 4020ms
Retry Behavior.Does Not Retry On 415 ✅ 4021ms
Retry Behavior.Non Retryable Errors Have No Retry After ✅ 4020ms
Retry Behavior.Implements Backoff ✅ 14033ms
Partial Batch Handling.Handles 200 Full Success ✅ 2018ms
Partial Batch Handling.Handles 200 With All Ok ✅ 3027ms
Partial Batch Handling.Does Not Retry Dropped Events ✅ 3024ms
Partial Batch Handling.Does Not Retry Warning Events ✅ 3024ms
Partial Batch Handling.Prunes Ok Events On Partial Retry ✅ 7017ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry ✅ 7018ms
Partial Batch Handling.Retries Only Retry Events From Partial ✅ 7013ms
Partial Batch Handling.Partial Retry Preserves Uuids ✅ 7018ms
Partial Batch Handling.Partial Retry Attempt Header Increments ✅ 7015ms
Partial Batch Handling.Partial Retry Request Id Preserved ✅ 7015ms
Partial Batch Handling.Respects Retry After On Partial ✅ 7025ms
Partial Batch Handling.Unknown Result Treated As Terminal ✅ 3023ms
Partial Batch Handling.Mixed Ok Drop Warning No Retry ✅ 3027ms
Compression.Sends Gzip Content Encoding ✅ 17ms
Compression.No Content Encoding When Disabled ✅ 15ms
Compression.Compressed Body Is Decompressible ✅ 11ms
Error Handling.Does Not Retry On Unknown 4Xx ✅ 4017ms
Event Options.Cookieless Mode Override ✅ 17ms
Event Options.Disable Skew Correction Override ✅ 12ms
Event Options.Process Person Profile Override ✅ 10ms
Event Options.Product Tour Id Override ✅ 12ms
Event Options.Unset Options Omitted ✅ 10ms
Event Options.Options Override In Batch ✅ 14ms
Event Options.Unknown Option Passes Through ✅ 12ms
Event Options.Option Value Is Not Converted ✅ 12ms
Event Options.Lenient Bool Option Values Are Not Converted ✅ 12ms
Event Options.Option Wins Over Legacy Property ✅ 12ms
Event Options.Legacy Property Fills Unset Option ✅ 12ms
Event Options.Null Option Falls Back To Legacy Property ✅ 12ms
Property Layers.Caller Property Beats Registered Property ✅ 12ms
Property Layers.Before Send Runs Last ✅ 15ms
Fail Open.Empty Api Key Sends Nothing ✅ 3009ms
Fail Open.Personal Api Key Sends Nothing ✅ 3014ms
Geoip And Historical Migration.Historical Migration Absent By Default ✅ 15ms

Capture_Ai_V1 Tests

✅ 110/110 tests passed

View Details
Test Status Duration
Endpoint And Method.Targets V1 Endpoint ✅ 14ms
Endpoint And Method.Does Not Use Legacy Endpoints ✅ 12ms
Endpoint And Method.Capture Does Not Reroute Ai Named Events ✅ 11ms
Endpoint And Method.Capture Ai Does Not Reroute Non Ai Events ✅ 11ms
Lane Isolation.Failing Ai Lane Does Not Delay Analytics ✅ 7015ms
Required Headers.Has Authorization Bearer Header ✅ 17ms
Required Headers.Has Content Type Json ✅ 14ms
Required Headers.Has Posthog Sdk Info Format ✅ 11ms
Required Headers.Has Posthog Attempt Header ✅ 12ms
Required Headers.Has Posthog Request Id ✅ 10ms
Required Headers.Has Posthog Request Timestamp ✅ 11ms
Required Headers.Has User Agent ✅ 11ms
Body Format.Body Has Created At And Batch ✅ 10ms
Body Format.No Api Key In Body ✅ 10ms
Body Format.No Sent At In Body ✅ 9ms
Event Format.Event Has Required Root Fields ✅ 12ms
Event Format.Event Uuid Is Valid ✅ 12ms
Event Format.Event Timestamp Is Rfc3339 ✅ 11ms
Event Format.Non Utc Event Timestamp Is Converted To Utc ✅ 10ms
Event Format.Distinct Id Is String ✅ 13ms
Event Format.Distinct Id At Root Not Properties ✅ 13ms
Event Format.Custom Properties Preserved ✅ 11ms
Event Format.Set Properties Preserved ✅ 11ms
Event Format.Set Once Properties Preserved ✅ 12ms
Event Format.Groups Properties Preserved ✅ 10ms
Event Format.Sdk Generates Uuid If Not Provided ✅ 12ms
Event Format.Event Has Required Root Fields Batch ✅ 14ms
Event Format.Event Uuid Is Valid Batch ✅ 14ms
Event Format.Event Timestamp Is Rfc3339 Batch ✅ 14ms
Event Format.Distinct Id Is String Batch ✅ 13ms
Event Format.Distinct Id At Root Not Properties Batch ✅ 14ms
Event Format.Custom Properties Preserved Batch ✅ 15ms
Event Format.Set Properties Preserved Batch ✅ 15ms
Event Format.Set Once Properties Preserved Batch ✅ 15ms
Event Format.Groups Properties Preserved Batch ✅ 18ms
Event Format.Sdk Generates Uuid If Not Provided Batch ✅ 13ms
Batch Behavior.Multiple Events In Single Batch ✅ 21ms
Batch Behavior.Batch Envelope Smoke ✅ 18ms
Batch Behavior.Flush At Triggers Batch ✅ 1012ms
Batch Behavior.Created At Reflects Batch Creation Time ✅ 16ms
Deduplication.Generates Unique Uuids ✅ 23ms
Deduplication.Different Events Same Content Different Uuids ✅ 15ms
Deduplication.Preserves Uuid On Retry ✅ 7014ms
Deduplication.Preserves Timestamp On Retry ✅ 7017ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 7019ms
Deduplication.No Duplicate Events In Batch ✅ 28ms
Header Behavior On Retry.Attempt Header Starts At One ✅ 12ms
Header Behavior On Retry.Attempt Header Increments On Retry ✅ 12021ms
Header Behavior On Retry.Request Id Preserved On Retry ✅ 7017ms
Header Behavior On Retry.Different Requests Have Different Request Ids ✅ 2027ms
Header Behavior On Retry.Request Timestamp Changes On Retry ✅ 7014ms
Response Format Validation.Success Response Has Uuid Keyed Results ✅ 16ms
Response Format Validation.Success Response Has Ok For Each Event ✅ 16ms
Response Format Validation.Success No Retry After When All Ok ✅ 15ms
Response Format Validation.Success Retry After Present When Retry Events ✅ 2016ms
Response Format Validation.Success No Retry After When Drop Only ✅ 19ms
Response Format Validation.Response Echoes Request Id ✅ 13ms
Retry Behavior.Retries On 408 ✅ 7010ms
Retry Behavior.Retries On 500 ✅ 7017ms
Retry Behavior.Retries On 503 ✅ 7023ms
Retry Behavior.Retries On 504 ✅ 7018ms
Retry Behavior.Retries On 404 ✅ 6011ms
Retry Behavior.Retries On 429 ✅ 6017ms
Retry Behavior.Retries On 502 ✅ 6017ms
Retry Behavior.Retryable Errors Have Retry After ✅ 4013ms
Retry Behavior.Respects Retry After On Retryable Error ✅ 10021ms
Retry Behavior.Does Not Retry On 400 ✅ 4020ms
Retry Behavior.Does Not Retry On 401 ✅ 4018ms
Retry Behavior.Does Not Retry On 402 ✅ 4017ms
Retry Behavior.Does Not Retry On 413 ✅ 4017ms
Retry Behavior.Does Not Retry On 415 ✅ 4019ms
Retry Behavior.Non Retryable Errors Have No Retry After ✅ 4017ms
Retry Behavior.Implements Backoff ✅ 14023ms
Partial Batch Handling.Handles 200 Full Success ✅ 2018ms
Partial Batch Handling.Handles 200 With All Ok ✅ 3024ms
Partial Batch Handling.Does Not Retry Dropped Events ✅ 3021ms
Partial Batch Handling.Does Not Retry Warning Events ✅ 3021ms
Partial Batch Handling.Prunes Ok Events On Partial Retry ✅ 7017ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry ✅ 7016ms
Partial Batch Handling.Retries Only Retry Events From Partial ✅ 7016ms
Partial Batch Handling.Partial Retry Preserves Uuids ✅ 7016ms
Partial Batch Handling.Partial Retry Attempt Header Increments ✅ 7017ms
Partial Batch Handling.Partial Retry Request Id Preserved ✅ 7015ms
Partial Batch Handling.Respects Retry After On Partial ✅ 7023ms
Partial Batch Handling.Unknown Result Treated As Terminal ✅ 3019ms
Partial Batch Handling.Mixed Ok Drop Warning No Retry ✅ 3025ms
Compression.Sends Gzip Content Encoding ✅ 18ms
Compression.No Content Encoding When Disabled ✅ 13ms
Compression.Compressed Body Is Decompressible ✅ 13ms
Error Handling.Does Not Retry On Unknown 4Xx ✅ 4013ms
Event Options.Cookieless Mode Override ✅ 16ms
Event Options.Disable Skew Correction Override ✅ 12ms
Event Options.Process Person Profile Override ✅ 12ms
Event Options.Product Tour Id Override ✅ 10ms
Event Options.Unset Options Omitted ✅ 12ms
Event Options.Options Override In Batch ✅ 16ms
Event Options.Unknown Option Passes Through ✅ 11ms
Event Options.Option Value Is Not Converted ✅ 12ms
Event Options.Lenient Bool Option Values Are Not Converted ✅ 11ms
Event Options.Option Wins Over Legacy Property ✅ 10ms
Event Options.Legacy Property Fills Unset Option ✅ 10ms
Event Options.Null Option Falls Back To Legacy Property ✅ 11ms
Event Size.Event Over Ceiling Is Not Sent ✅ 3288ms
Event Size.Over Ceiling Drop Is Reported Or Logged Without Content ✅ 2051ms
Event Size.Batches Close Before Byte Target ✅ 6070ms
Geoip And Historical Migration.Historical Migration Absent By Default ✅ 17ms
Property Layers.Caller Property Beats Registered Property ✅ 11ms
Property Layers.Before Send Runs Last ✅ 11ms
Fail Open.Empty Api Key Sends Nothing ✅ 1008ms
Fail Open.Personal Api Key Sends Nothing ✅ 1012ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details
Test Status Duration
Request Payload.Request With Person Properties Device Id ✅ 31ms
Request Payload.Flags Request Uses V2 Query Param ✅ 14ms
Request Payload.Flags Request Hits Flags Path Not Decide ✅ 13ms
Request Payload.Flags Request Omits Authorization Header ✅ 12ms
Request Payload.Token In Flags Body Matches Init ✅ 12ms
Request Payload.Groups Round Trip ✅ 14ms
Request Payload.Groups Default To Empty Object ✅ 16ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False ✅ 15ms
Request Payload.Disable Geoip Omitted Defaults To False ✅ 11ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key ✅ 12ms
Request Lifecycle.No Flags Request On Init Alone ✅ 5ms
Request Lifecycle.No Flags Request On Normal Capture ✅ 10ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests ✅ 15ms
Request Lifecycle.Mock Response Value Is Returned To Caller ✅ 13ms
Retry Behavior.Retries Flags On 502 ✅ 316ms
Retry Behavior.Retries Flags On 504 ✅ 318ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event ✅ 16ms

@turnipdabeets
turnipdabeets force-pushed the feat/v4-capture-v1 branch 2 times, most recently from e4e5fc5 to 8a765aa Compare October 24, 2026 18:13
@turnipdabeets
turnipdabeets force-pushed the chore/v4-remove-deprecated branch from 2f486a0 to a41d9b9 Compare October 26, 2026 16:29
@turnipdabeets
turnipdabeets changed the base branch from chore/v4-remove-deprecated to main October 26, 2026 18:03
@turnipdabeets
turnipdabeets added this pull request to stack #888 October 26, 2026 18:03
@turnipdabeets
turnipdabeets removed this pull request from stack #888 October 26, 2026 18:06
@turnipdabeets
turnipdabeets changed the base branch from main to chore/v4-remove-deprecated October 26, 2026 18:06
@turnipdabeets
turnipdabeets added this pull request to stack #890 October 26, 2026 18:06
@turnipdabeets
turnipdabeets marked this pull request as ready for review October 26, 2026 18:44
@turnipdabeets
turnipdabeets requested a review from a team as a code owner October 26, 2026 18:44
@turnipdabeets
turnipdabeets force-pushed the chore/v4-remove-deprecated branch from a41d9b9 to caf64bd Compare October 26, 2026 18:47

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

PostHog Review · Standard · reviewed 483626f: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

PostHog Review · Standard · reviewed c7fec3a: 1 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

@veria-ai

veria-ai Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

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

Comment thread docs/migration-3.x-to-4.0.md Resolved

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

PostHog Review · Standard · reviewed 1426e51: 1 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

This is review round 3 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

turnipdabeets and others added 2 commits October 27, 2026 12:58
A `phx_` token is a personal API key; capture rejects every request made
with it. Setup now logs once and stays disabled, as for an empty token.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Analytics events now go to `POST /i/v1/analytics/events` with the project
token in an `Authorization: Bearer` header, `PostHog-Sdk-Info`,
`PostHog-Attempt`, `PostHog-Request-Id` and `PostHog-Request-Timestamp`.
The body is `{created_at, batch}`; each event drops `$lib`/`$lib_version`,
lifts string `$session_id`/`$window_id` to the root, and hoists the legacy
`$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at` and
`$product_tour_id` properties into the new `PostHogEvent.options`.

The queue reads the per-event results: `ok`, `warning` and `drop` leave the
queue, only `retry` is kept and resent under the same request id and
`created_at` with the next attempt number. A 2xx without readable results
counts as delivered. 408 and 500/502/503/504 are retried; 429, 404 and
other 4xx are terminal, as are redirects other than a same-origin 307/308
(followed at most 5 times with the same body and headers). Backoff doubles
from 1 to 30 seconds with 25% jitter, and `Retry-After` is a floor capped
at 30 seconds for every queue. Replay and logs keep their retry sets.

Legacy cached events (`PostHogSendCachedEventsIntegration`) are sent
through capture v1 too; the ones capture asks to retry are re-queued at
the tail of the legacy file for the next launch.

`PostHogConfig.maxRetries` is renamed `pushNotificationSubscriptionMaxRetries`
since it only limits push-subscription retries. `PostHogApi.batch()` stays
for posthog-server.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…y and typed values (#903)

* fix: match the capture v1 rules for empty names, drop logs, retry identity and typed values

* fix: merge a $groups map in properties into the groups set with group()

* fix: log an empty-name drop once, without the generic dropped-event line

* fix: clamp each duplicates_dropped count to the batch size

* fix: keep the pending retry map off Java 8 Map methods missing on API 23

* fix: keep the personless option over a legacy property and drop a 2xx without results (#905)

* fix: keep the personless option when a legacy person processing property is set

A passed or registered `$process_person_profile` property no longer stops
the SDK from setting `process_person_profile: false` when person
processing is off. The send hoists the property only into an unset
option, so an option set by any layer wins, as the capture spec requires.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: treat a 2xx without readable per-event results as a terminal failure

A 2xx whose body can't be read as `{"results": {...}}` no longer counts
the batch as delivered. It throws a PostHogApiError with that status,
which the queue drops without retrying, and logs only the status and
event count, as the capture spec requires.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

* fix: warn about empty and personal API keys without debug and log rejected batches (#909)

* fix: let a caller's $process_person_profile override the personless option

Reverts the person-processing half of #905. A passed or registered
`$process_person_profile` property again stops the SDK from adding
`process_person_profile: false` when person processing is off, so the
caller wins, as the client property precedence in sdk-specs `capture`
(#143) requires. The send still hoists the property into the option.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: log drop reasons per batch and batch migrated legacy events by bytes

- The capture v1 per-batch debug line names the endpoint and counts the
  dropped events by their `details` tag (opaque strings, never uuids or
  content), e.g. `ai_event_too_big: 1, misrouted_event: 1`.
- Sending events cached by 2.x/3.x closes a batch before it would pass
  the 5 MiB capture v1 byte target, as the queue does, so a large
  migrated batch isn't lost to a 413. Order is kept and an event over
  the target ships alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: say the token warnings print without debug

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: name the records in the flush drop log

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: cover the capture rules on the captureStateless path

Also adds the posthog-server changeset for them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: fold the server capture changes into the server changeset

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
turnipdabeets and others added 6 commits November 2, 2026 20:57
* docs: ask users to review beforeSend hooks for the 4.0 event shape

* docs: cover replacing event.options in beforeSend

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
)

* feat!: report the device language as $locale and add $app_language

* fix: address the pre-PR review of $locale and $app_language

* docs: correct the $locale migration notes

* fix: read a registered $app_language without relying on merge order

* fix: read locales and the locale config only on the worker thread

Setup and capture no longer make Binder calls or parse the locale config, and
supported locales changed at runtime with setOverrideLocaleConfig are picked up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: leave out $app_language when several declared regions could match

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: stop reading a registered $app_language on every event

Registered properties are merged later and win anyway.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: guard LocaleList calls for the API 23 lint check

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: read the override locale config only when the locales change

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: say when $app_language is left out with no match

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…929)

* fix: align capture v1 logs, request IDs and beforeSend handling

* fix: copy arrays and cycles for beforeSend, and keep the hook failure log debug-only

* fix: keep array types in the copy beforeSend hooks get

* fix: keep sorted map lookups and copy primitive arrays for beforeSend

* fix: read an HTTP-date Retry-After

* fix: log the key type when a map key can't be serialized
turnipdabeets and others added 2 commits November 3, 2026 14:04
… feat/v4-capture-v1

# Conflicts:
#	docs/migration-3.x-to-4.0.md
…the backend guides (#934)

* docs: link the capture v1 SDK upgrade guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: add timestamps, UUID v7 and the person-only drop to the 4.0 guide

* docs: align the 4.0 capture v1 guide with the backend SDK guides

Claude-Session: https://claude.ai/code/session_019xLynws83apuXa9LfRy9Aq

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
turnipdabeets and others added 3 commits November 4, 2026 16:36
posthog-server is a minor release and its beforeSend gets PostHogEvent,
so a new trailing constructor parameter broke Java callers and copy
calls compiled against 3.x. options is now a property. When beforeSend
returns a different event with null options, such as a copy, it keeps
the options of the event the hook was given.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Remove the two internal TODO comments.
- Say surveys-compose works with core 6.x and 7.0.
- List RRStyle and the trimmed RRWireframe under internal APIs.
- captureAi also returns null for an empty event name.
- Note per-event product quota drops, the per-batch drop reasons and
  the removed per-event "queued" log line.
- Self-hosting needs /i/v1/ai/events for captureAi.
- A whitespace-only token disables the SDK too.
- Describe the 3.x $set/$set_once/$groups replacement rule and the
  registered $set rule.
- KDoc: the AI size drop logs the limit, not the event's size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… feat/v4-capture-v1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… feat/v4-capture-v1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@turnipdabeets
turnipdabeets removed this pull request from stack #890 November 5, 2026 15:04
@turnipdabeets
turnipdabeets merged commit df58692 into chore/v4-remove-deprecated Nov 5, 2026
17 checks passed
@turnipdabeets
turnipdabeets deleted the feat/v4-capture-v1 branch November 5, 2026 15:05
gewenyu99 added a commit that referenced this pull request Nov 11, 2026
)

* docs: generate the SDK reference for 3.x

Generated by bin/docs_scripts/generate_markdown.py.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs: generate the experimental SDK reference for 4.x

Generated by bin/docs_scripts/generate_markdown.py --major 4 --experimental from feat/v4-capture-v1 (PRs #871 and #881), with the capability tags applied on top. Adds the 3.x to 4.0 migration guide page.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

* docs: regenerate the Android references from Dokka's HTML

The 4.x page and migration guide come from chore/v4-remove-deprecated (the 4.0
branch) with the capability tags and getting-started applied. Both still need to
land there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Android references with braces kept in code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Android references from docs/capabilities.json

The 3.x pages lose only the blank line the stripped capability tags left behind. The 4.x page also
moves captureAi to Capture AI and onFeatureFlags to On feature flags, which the map's "next"
entries add.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Android references after review fixes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Android migration page from the current 4.0 guide

Rebuilt from docs/migration-3.x-to-4.0.md on chore/v4-remove-deprecated,
which dropped the SDK identity section (#942) and added the custom
httpClient paragraph.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Android migration page from the current 4.0 guide

Rebuilt from docs/migration-3.x-to-4.0.md on chore/v4-remove-deprecated,
which now covers the missing-flag response, posthog-server 2.25 and retry scope.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the Android 4.x page from chore/v4-remove-deprecated

Picks up the branch's feature flag doc comment fixes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: regenerate the references with the getting-started intro

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
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.

4 participants