Skip to content

fix: match capture v1 rules for empty names, drop logs, retry identity and typed values - #903

Open
turnipdabeets wants to merge 22 commits into
feat/v4-capture-v1from
fix/v4-v1-rubric-followups
Open

turnipdabeets wants to merge 22 commits into
feat/v4-capture-v1from
fix/v4-v1-rubric-followups

Conversation

@turnipdabeets

@turnipdabeets turnipdabeets commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

💡 Motivation and Context

Follow-ups on the capture v1 branch (#881) to match the fleet rules the other v1 SDKs follow:

  • Empty event names are dropped locally. capture(""), or a beforeSend that renames an event to "", is dropped before sending and logged once (debug). Capture drops these anyway; now they never leave the device. Only an exactly-empty name, same as iOS #989 and Flutter desktop fix(server): keep locally evaluated flags when one flag is inconclusive #681.
  • Drop logging is one count line per batch. No more debug line per dropped event (it named the event and uuid). The line now also counts the duplicate copies capture dropped (duplicates_dropped), matching iOS.
  • A retry keeps its request identity when other events are sent in between. Before, a send with a different set of events (for example the fatal-event path) replaced the pending identity, so the retried batch went out as attempt 1 with a new request id. Identities are now kept per endpoint and event set (capped at 16).
  • Typed per-call values win key by key. userProperties, userPropertiesSetOnce and groups are merged over a $set, $set_once or $groups map passed in the same call's properties, instead of being replaced by it.
  • A $groups map in properties adds to the groups set with group() instead of replacing them; typed groups still win per key. Matches iOS.
  • Migration guide and the 4.0 changeset updated for the above, plus a line that NaN and infinite numbers are dropped from the properties.

Not changed here: if capture asks to retry a uuid that was duplicated in the batch, the queue still keeps every copy of that uuid. The SDK never sends duplicate uuids itself, so this only happens after a beforeSend bug.

💚 How did you test it?

  • New unit tests for each change: they fail on the base branch and pass here.
  • ./gradlew :posthog:test :posthog-android:testDebugUnitTest :posthog:apiCheck spotlessCheck pass.

📝 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 pnpm changeset to generate a changeset file (updated the existing 4.0 major changeset)

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

  • Claude Code compared the v1 branch against the capture v1 requirements shared by the SDK team, then made these fixes.
  • iOS #989 applies the same typed-value and $groups merge rules, so both SDKs build these maps the same way.

🤖 Generated with Claude Code

@turnipdabeets turnipdabeets self-assigned this Oct 28, 2026
@turnipdabeets
turnipdabeets requested a review from a team as a code owner October 28, 2026 23:50

@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 0f90073: 1 Should fix.

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 29, 2026 •

Copy link
Copy Markdown
Contributor

posthog-android Compliance Report

Date: 2026-10-31T02:25:10.553732+00:00
Duration: 476763ms

✅ 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 ✅ 401ms
Endpoint And Method.Does Not Use Legacy Endpoints ✅ 31ms
Required Headers.Has Authorization Bearer Header ✅ 28ms
Required Headers.Has Content Type Json ✅ 25ms
Required Headers.Has Posthog Sdk Info Format ✅ 28ms
Required Headers.Has Posthog Attempt Header ✅ 26ms
Required Headers.Has Posthog Request Id ✅ 28ms
Required Headers.Has Posthog Request Timestamp ✅ 27ms
Required Headers.Has User Agent ✅ 26ms
Body Format.Body Has Created At And Batch ✅ 23ms
Body Format.No Api Key In Body ✅ 28ms
Body Format.No Sent At In Body ✅ 23ms
Event Format.Event Has Required Root Fields ✅ 23ms
Event Format.Event Uuid Is Valid ✅ 22ms
Event Format.Event Timestamp Is Rfc3339 ✅ 25ms
Event Format.Non Utc Event Timestamp Is Converted To Utc ✅ 26ms
Event Format.Distinct Id Is String ✅ 21ms
Event Format.Distinct Id At Root Not Properties ✅ 21ms
Event Format.Custom Properties Preserved ✅ 21ms
Event Format.Set Properties Preserved ✅ 24ms
Event Format.Set Once Properties Preserved ✅ 23ms
Event Format.Groups Properties Preserved ✅ 23ms
Event Format.Sdk Generates Uuid If Not Provided ✅ 24ms
Event Format.Event Has Required Root Fields Batch ✅ 29ms
Event Format.Event Uuid Is Valid Batch ✅ 29ms
Event Format.Event Timestamp Is Rfc3339 Batch ✅ 29ms
Event Format.Distinct Id Is String Batch ✅ 25ms
Event Format.Distinct Id At Root Not Properties Batch ✅ 26ms
Event Format.Custom Properties Preserved Batch ✅ 32ms
Event Format.Set Properties Preserved Batch ✅ 26ms
Event Format.Set Once Properties Preserved Batch ✅ 25ms
Event Format.Groups Properties Preserved Batch ✅ 26ms
Event Format.Sdk Generates Uuid If Not Provided Batch ✅ 38ms
Batch Behavior.Multiple Events In Single Batch ✅ 35ms
Batch Behavior.Batch Envelope Smoke ✅ 28ms
Batch Behavior.Flush With No Events Sends Nothing ✅ 15ms
Batch Behavior.Flush At Triggers Batch ✅ 1024ms
Batch Behavior.Created At Reflects Batch Creation Time ✅ 20ms
Deduplication.Generates Unique Uuids ✅ 48ms
Deduplication.Different Events Same Content Different Uuids ✅ 27ms
Deduplication.Preserves Uuid On Retry ✅ 7014ms
Deduplication.Preserves Timestamp On Retry ✅ 7018ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 7025ms
Deduplication.No Duplicate Events In Batch ✅ 30ms
Header Behavior On Retry.Attempt Header Starts At One ✅ 17ms
Header Behavior On Retry.Attempt Header Increments On Retry ✅ 12019ms
Header Behavior On Retry.Request Id Preserved On Retry ✅ 7017ms
Header Behavior On Retry.Different Requests Have Different Request Ids ✅ 2028ms
Header Behavior On Retry.Request Timestamp Changes On Retry ✅ 7016ms
Response Format Validation.Success Response Has Uuid Keyed Results ✅ 17ms
Response Format Validation.Success Response Has Ok For Each Event ✅ 21ms
Response Format Validation.Success No Retry After When All Ok ✅ 20ms
Response Format Validation.Success Retry After Present When Retry Events ✅ 2012ms
Response Format Validation.Success No Retry After When Drop Only ✅ 19ms
Response Format Validation.Response Echoes Request Id ✅ 17ms
Retry Behavior.Retries On 408 ✅ 7015ms
Retry Behavior.Retries On 500 ✅ 7017ms
Retry Behavior.Retries On 503 ✅ 7020ms
Retry Behavior.Retries On 504 ✅ 7012ms
Retry Behavior.Retries On 404 ✅ 7017ms
Retry Behavior.Retries On 429 ✅ 6016ms
Retry Behavior.Retries On 502 ✅ 7016ms
Retry Behavior.Retryable Errors Have Retry After ✅ 4011ms
Retry Behavior.Respects Retry After On Retryable Error ✅ 10025ms
Retry Behavior.Does Not Retry On 400 ✅ 4018ms
Retry Behavior.Does Not Retry On 401 ✅ 4020ms
Retry Behavior.Does Not Retry On 402 ✅ 4017ms
Retry Behavior.Does Not Retry On 413 ✅ 4018ms
Retry Behavior.Does Not Retry On 415 ✅ 4023ms
Retry Behavior.Non Retryable Errors Have No Retry After ✅ 4017ms
Retry Behavior.Implements Backoff ✅ 14030ms
Partial Batch Handling.Handles 200 Full Success ✅ 2017ms
Partial Batch Handling.Handles 200 With All Ok ✅ 3026ms
Partial Batch Handling.Does Not Retry Dropped Events ✅ 3023ms
Partial Batch Handling.Does Not Retry Warning Events ✅ 3030ms
Partial Batch Handling.Prunes Ok Events On Partial Retry ✅ 7015ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry ✅ 7017ms
Partial Batch Handling.Retries Only Retry Events From Partial ✅ 7012ms
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 ✅ 7016ms
Partial Batch Handling.Respects Retry After On Partial ✅ 7024ms
Partial Batch Handling.Unknown Result Treated As Terminal ✅ 3020ms
Partial Batch Handling.Mixed Ok Drop Warning No Retry ✅ 3027ms
Compression.Sends Gzip Content Encoding ✅ 15ms
Compression.No Content Encoding When Disabled ✅ 18ms
Compression.Compressed Body Is Decompressible ✅ 16ms
Error Handling.Does Not Retry On Unknown 4Xx ✅ 4016ms
Event Options.Cookieless Mode Override ✅ 15ms
Event Options.Disable Skew Correction Override ✅ 12ms
Event Options.Process Person Profile Override ✅ 14ms
Event Options.Product Tour Id Override ✅ 12ms
Event Options.Unset Options Omitted ✅ 15ms
Event Options.Options Override In Batch ✅ 19ms
Event Options.Unknown Option Passes Through ✅ 15ms
Event Options.Option Value Is Not Converted ✅ 16ms
Event Options.Lenient Bool Option Values Are Not Converted ✅ 18ms
Event Options.Option Wins Over Legacy Property ✅ 13ms
Event Options.Legacy Property Fills Unset Option ✅ 16ms
Event Options.Null Option Falls Back To Legacy Property ✅ 17ms
Property Layers.Caller Property Beats Registered Property ✅ 19ms
Property Layers.Before Send Runs Last ✅ 20ms
Fail Open.Empty Api Key Sends Nothing ✅ 3012ms
Fail Open.Personal Api Key Sends Nothing ✅ 3012ms
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 ✅ 15ms
Endpoint And Method.Does Not Use Legacy Endpoints ✅ 16ms
Endpoint And Method.Capture Does Not Reroute Ai Named Events ✅ 14ms
Endpoint And Method.Capture Ai Does Not Reroute Non Ai Events ✅ 15ms
Lane Isolation.Failing Ai Lane Does Not Delay Analytics ✅ 7026ms
Required Headers.Has Authorization Bearer Header ✅ 16ms
Required Headers.Has Content Type Json ✅ 20ms
Required Headers.Has Posthog Sdk Info Format ✅ 20ms
Required Headers.Has Posthog Attempt Header ✅ 19ms
Required Headers.Has Posthog Request Id ✅ 15ms
Required Headers.Has Posthog Request Timestamp ✅ 14ms
Required Headers.Has User Agent ✅ 14ms
Body Format.Body Has Created At And Batch ✅ 17ms
Body Format.No Api Key In Body ✅ 16ms
Body Format.No Sent At In Body ✅ 17ms
Event Format.Event Has Required Root Fields ✅ 17ms
Event Format.Event Uuid Is Valid ✅ 16ms
Event Format.Event Timestamp Is Rfc3339 ✅ 13ms
Event Format.Non Utc Event Timestamp Is Converted To Utc ✅ 15ms
Event Format.Distinct Id Is String ✅ 16ms
Event Format.Distinct Id At Root Not Properties ✅ 14ms
Event Format.Custom Properties Preserved ✅ 14ms
Event Format.Set Properties Preserved ✅ 17ms
Event Format.Set Once Properties Preserved ✅ 20ms
Event Format.Groups Properties Preserved ✅ 18ms
Event Format.Sdk Generates Uuid If Not Provided ✅ 18ms
Event Format.Event Has Required Root Fields Batch ✅ 18ms
Event Format.Event Uuid Is Valid Batch ✅ 21ms
Event Format.Event Timestamp Is Rfc3339 Batch ✅ 21ms
Event Format.Distinct Id Is String Batch ✅ 24ms
Event Format.Distinct Id At Root Not Properties Batch ✅ 22ms
Event Format.Custom Properties Preserved Batch ✅ 21ms
Event Format.Set Properties Preserved Batch ✅ 22ms
Event Format.Set Once Properties Preserved Batch ✅ 23ms
Event Format.Groups Properties Preserved Batch ✅ 27ms
Event Format.Sdk Generates Uuid If Not Provided Batch ✅ 25ms
Batch Behavior.Multiple Events In Single Batch ✅ 30ms
Batch Behavior.Batch Envelope Smoke ✅ 26ms
Batch Behavior.Flush At Triggers Batch ✅ 1017ms
Batch Behavior.Created At Reflects Batch Creation Time ✅ 17ms
Deduplication.Generates Unique Uuids ✅ 29ms
Deduplication.Different Events Same Content Different Uuids ✅ 17ms
Deduplication.Preserves Uuid On Retry ✅ 7015ms
Deduplication.Preserves Timestamp On Retry ✅ 7014ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry ✅ 7016ms
Deduplication.No Duplicate Events In Batch ✅ 29ms
Header Behavior On Retry.Attempt Header Starts At One ✅ 17ms
Header Behavior On Retry.Attempt Header Increments On Retry ✅ 12024ms
Header Behavior On Retry.Request Id Preserved On Retry ✅ 7015ms
Header Behavior On Retry.Different Requests Have Different Request Ids ✅ 2023ms
Header Behavior On Retry.Request Timestamp Changes On Retry ✅ 7015ms
Response Format Validation.Success Response Has Uuid Keyed Results ✅ 15ms
Response Format Validation.Success Response Has Ok For Each Event ✅ 20ms
Response Format Validation.Success No Retry After When All Ok ✅ 20ms
Response Format Validation.Success Retry After Present When Retry Events ✅ 2009ms
Response Format Validation.Success No Retry After When Drop Only ✅ 19ms
Response Format Validation.Response Echoes Request Id ✅ 13ms
Retry Behavior.Retries On 408 ✅ 7014ms
Retry Behavior.Retries On 500 ✅ 7012ms
Retry Behavior.Retries On 503 ✅ 7022ms
Retry Behavior.Retries On 504 ✅ 7015ms
Retry Behavior.Retries On 404 ✅ 7013ms
Retry Behavior.Retries On 429 ✅ 6012ms
Retry Behavior.Retries On 502 ✅ 7016ms
Retry Behavior.Retryable Errors Have Retry After ✅ 4011ms
Retry Behavior.Respects Retry After On Retryable Error ✅ 10023ms
Retry Behavior.Does Not Retry On 400 ✅ 4018ms
Retry Behavior.Does Not Retry On 401 ✅ 4016ms
Retry Behavior.Does Not Retry On 402 ✅ 4017ms
Retry Behavior.Does Not Retry On 413 ✅ 4018ms
Retry Behavior.Does Not Retry On 415 ✅ 4016ms
Retry Behavior.Non Retryable Errors Have No Retry After ✅ 4016ms
Retry Behavior.Implements Backoff ✅ 14020ms
Partial Batch Handling.Handles 200 Full Success ✅ 2017ms
Partial Batch Handling.Handles 200 With All Ok ✅ 3025ms
Partial Batch Handling.Does Not Retry Dropped Events ✅ 3021ms
Partial Batch Handling.Does Not Retry Warning Events ✅ 3022ms
Partial Batch Handling.Prunes Ok Events On Partial Retry ✅ 7016ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry ✅ 7014ms
Partial Batch Handling.Retries Only Retry Events From Partial ✅ 7015ms
Partial Batch Handling.Partial Retry Preserves Uuids ✅ 7015ms
Partial Batch Handling.Partial Retry Attempt Header Increments ✅ 7014ms
Partial Batch Handling.Partial Retry Request Id Preserved ✅ 7015ms
Partial Batch Handling.Respects Retry After On Partial ✅ 7022ms
Partial Batch Handling.Unknown Result Treated As Terminal ✅ 3021ms
Partial Batch Handling.Mixed Ok Drop Warning No Retry ✅ 3025ms
Compression.Sends Gzip Content Encoding ✅ 15ms
Compression.No Content Encoding When Disabled ✅ 17ms
Compression.Compressed Body Is Decompressible ✅ 17ms
Error Handling.Does Not Retry On Unknown 4Xx ✅ 4014ms
Event Options.Cookieless Mode Override ✅ 14ms
Event Options.Disable Skew Correction Override ✅ 14ms
Event Options.Process Person Profile Override ✅ 15ms
Event Options.Product Tour Id Override ✅ 15ms
Event Options.Unset Options Omitted ✅ 13ms
Event Options.Options Override In Batch ✅ 19ms
Event Options.Unknown Option Passes Through ✅ 20ms
Event Options.Option Value Is Not Converted ✅ 18ms
Event Options.Lenient Bool Option Values Are Not Converted ✅ 15ms
Event Options.Option Wins Over Legacy Property ✅ 16ms
Event Options.Legacy Property Fills Unset Option ✅ 20ms
Event Options.Null Option Falls Back To Legacy Property ✅ 19ms
Event Size.Event Over Ceiling Is Not Sent ✅ 3446ms
Event Size.Over Ceiling Drop Is Reported Or Logged Without Content ✅ 2051ms
Event Size.Batches Close Before Byte Target ✅ 6085ms
Geoip And Historical Migration.Historical Migration Absent By Default ✅ 16ms
Property Layers.Caller Property Beats Registered Property ✅ 13ms
Property Layers.Before Send Runs Last ✅ 14ms
Fail Open.Empty Api Key Sends Nothing ✅ 1009ms
Fail Open.Personal Api Key Sends Nothing ✅ 1011ms

Feature_Flags Tests

✅ 17/17 tests passed

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

turnipdabeets and others added 2 commits October 29, 2026 10:53
… 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 <[email protected]>

* 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 <[email protected]>

---------

Co-authored-by: Claude Opus 5.5 <[email protected]>

@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 aaf7664: 1 Should fix.

turnipdabeets and others added 2 commits October 29, 2026 14:46
…ption

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 <[email protected]>
turnipdabeets and others added 3 commits October 29, 2026 16:23
…ytes

- 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 <[email protected]>
…v1-rubric-followups

Moves this branch's queue changes into enqueueEvent(), where #904 put capture's queueing step.

@eli-r-ph eli-r-ph 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.

A personal API key (`phx_...`) in `projectToken` now disables the SDK at setup, as an empty token does, and logs why when `debug` is on.

Both token messages now print with logWarning, also without debug, so this line can say so and mention the empty token too.

logger.log("Flushing failed with ${e.statusCode}, let's try again with a smaller batch.")

"Flushing failed with N, dropping M records" doesn't say which queue or endpoint. Could it include the queue's label?

if (config.projectToken.isEmpty()) {
config.logger.log(
config.logger.logWarning(
"PostHog SDK is disabled because the project token is required and was empty after trimming whitespace.",

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-server goes through this path, so it now drops empty event names, merges typed $set/$set_once/$groups per key, and prints these warnings without debug. Could a posthog-server changeset say so, and a test cover the captureStateless path?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 15e60c7 — added a posthog-server changeset and captureStateless tests for empty names and typed merges.

This branch has not been deployed

No deployments
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