feat(capture): route analytics through v1 submitter (capture v1, 4/6)#704
Merged
Conversation
Contributor
|
Reviews (1): Last reviewed commit: "feat(capture): route analytics through v..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
4 tasks
Contributor
posthog-python Compliance ReportDate: 2026-07-06 21:09:53 UTC ✅ All Tests Passed!111/111 tests passed Capture_V1 Tests✅ 94/94 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
|
eli-r-ph
force-pushed
the
capture-v1/03-transport
branch
from
a901fdc to
7fd7dcd
Compare
eli-r-ph
force-pushed
the
capture-v1/04-wire
branch
2 times, most recently
from
3274be1 to
5026185
Compare
eli-r-ph
force-pushed
the
capture-v1/03-transport
branch
2 times, most recently
from
32d7b02 to
3677400
Compare
eli-r-ph
force-pushed
the
capture-v1/04-wire
branch
from
5026185 to
d1875fc
Compare
eli-r-ph
force-pushed
the
capture-v1/04-wire
branch
from
d1875fc to
73e034f
Compare
eli-r-ph
force-pushed
the
capture-v1/03-transport
branch
from
3677400 to
c698bd5
Compare
Contributor
|
Reviews (2): Last reviewed commit: "feat(capture): wire capture_compression ..." | Re-trigger Greptile |
eli-r-ph
force-pushed
the
capture-v1/04-wire
branch
2 times, most recently
from
0b0adf7 to
335afbc
Compare
marandaneto
approved these changes
Jul 6, 2026
eli-r-ph
force-pushed
the
capture-v1/04-wire
branch
from
335afbc to
aecbab1
Compare
eli-r-ph
force-pushed
the
capture-v1/03-transport
branch
from
58cb3e5 to
46bbd7d
Compare
eli-r-ph
force-pushed
the
capture-v1/04-wire
branch
from
aecbab1 to
1210124
Compare
Wires send_v1_batch into both send paths so capture_mode actually takes effect end to end. The consumer's async path (Consumer.request) and the client's sync path (_enqueue) now pick the analytics submitter by capture_mode: v1 -> the partial-retry send loop, v0 -> the legacy batch_post. The dedicated AI endpoint has no v1 form, so $ai_* events on it always use the legacy submitter regardless of capture_mode. Refactors Consumer.request to route via _send_analytics/_send_ai helpers, stores Client.max_retries so the sync path can pass it through, and forwards gzip/timeout/retries/historical_migration to the v1 submitter. Default is still v0, so existing callers are unaffected. Adds consumer routing-matrix tests (v0/v1, dedicated-AI split, config forwarding) and client sync-mode tests (v0 vs v1, dedicated-AI event stays legacy, analytics event uses v1). ruff/mypy clean.
Resolve capture_compression once on the client (kwarg > env > legacy gzip flag > none) and thread it to the v1 submitter via the consumer and the sync path. Parameterize the capture_mode routing tests and use consistent submitter labels.
eli-r-ph
force-pushed
the
capture-v1/04-wire
branch
from
1210124 to
4afa7c7
Compare
* chore(capture): add v1 compliance adapter mode and CI job Teaches the SDK compliance adapter to speak capture-v1 and adds a second CI job that runs the harness capture_v1 suite against it. Splits the workflow into v0 + v1 jobs, both on the 0.10.0 harness (which carries the capture_v1 suites), and adds adapter timing/debug settings for reliable test execution. * chore(capture): document capture_mode + release changeset (capture v1, 6/6) (#706) * docs(capture): document capture_mode, capture_compression, and changeset Adds the Sampo changeset for the opt-in capture_mode (v1 ingestion protocol) and capture_compression, plus an AGENTS.md section mapping capture_mode/capture_compression and their env vars to the modules and routing that implement them, the v1 invariants to preserve, and the sync_mode blocking-retry behavior. User-facing usage stays in the official docs per the README convention. * docs(capture): note v1 drop surfacing and Retry-After minimum Document the two parity behaviors added to the v1 transport: server `drop` verdicts are accumulated across attempts and surfaced via CaptureV1Error/ on_error even on a 2xx, and Retry-After acts as a minimum (max of configured backoff and Retry-After, hard-capped) rather than a replacement. * docs(capture): note the unified 30s retry backoff ceiling MAX_BACKOFF_SECONDS (30s) caps both the exponential backoff and the Retry-After clamp; update the v1 invariants note accordingly. * docs(capture): document zstd compression and private helper names
eli-r-ph
added a commit
that referenced
this pull request
Jul 6, 2026
…6) (#703) * feat(capture): add v1 transport and partial-retry send loop Adds the HTTP transport for POST /i/v1/analytics/events alongside the pure transforms: a single Bearer-authed attempt (post_v1) with the required v1 headers, response classification (parse_v1_response), and the send loop (send_v1_batch) that resends only the events the server tags "retry", logs drops, honors Retry-After, and raises CaptureV1Error on terminal/transport failure or retry exhaustion so the consumer's existing on_error path fires unchanged. 429 is terminal in v1 (unlike v0). A 2xx with an unparseable body is terminal to avoid an infinite resend loop. A stable PostHog-Request-Id and created_at span attempts; PostHog-Attempt increments. Factors a shared gzip_compress helper out of request.post (no v0 behavior change). Still inert: nothing calls send_v1_batch until the consumer wiring PR. 74 capture_v1 tests (47 transform + 27 transport); ruff/mypy clean. * fix(capture): stabilize v1 created_at, isolate compression, quiet drops Address review of the v1 transport: - Hoist the batch created_at out of the retry loop so the envelope stays stable across attempts (only the events list and PostHog-Attempt change). - Isolate v1 request compression behind a CaptureCompression selector supporting gzip and zlib-wrapped deflate (RFC 1950), reverting the gzip_compress extraction from request.py so the v1 path owns its codecs. - Stop logging per-event drops at WARNING; a server-chosen drop on a 2xx is not a delivery failure and is already carried on CaptureV1Error for batch-level surfacing via on_error. * fix(capture): surface v1 drops and treat Retry-After as a minimum Address review of the v1 transport (#703): - Accumulate server `drop` verdicts across all attempts and raise CaptureV1Error even on a 2xx with no retry events (a success status is not full delivery) and when a later attempt clears the retries, so on_error sees every dropped uuid. Drops also ride along on the retry-exhaustion, malformed-2xx, and terminal non-2xx errors. - _backoff treats Retry-After as a minimum (max of configured backoff and Retry-After), hard-capped at 1 day, matching posthog-go/posthog-rs so a small header can't retry earlier than the schedule and a hostile one can't park the consumer thread. Adds drop-surfacing and backoff tests; regenerates public_api_snapshot. * fix(capture): unify v1 retry backoff ceiling at 30s Replace the 1-day RETRY_BACKOFF_CAP_SECONDS with a single MAX_BACKOFF_SECONDS (30s) that both caps the exponential backoff and clamps the server Retry-After, so the max retry wait is bounded and the default matches posthog-go/posthog-rs. Retry-After remains a minimum; there is no separate large cap. * refactor(capture): privatize v1 transport and compression resolver Underscore-prefix the transport layer (post_v1, parse_v1_response, send_v1_batch, response dataclasses, backoff ceiling) and the compression resolver; declare __all__ so the public surface is CaptureCompression, its env var name, and CaptureV1Error (which reaches user code via on_error callbacks). Re-export CaptureCompression at the package top level for symmetry with CaptureMode. * feat(capture): add optional zstd compression for capture v1 Add CaptureCompression.ZSTD backed by the optional zstandard package (pip install posthog[zstd]); Python has no stdlib zstd until 3.14. Explicitly requesting zstd without the package raises ValueError (fail loud at construction); requesting it via POSTHOG_CAPTURE_COMPRESSION warns and falls back so operator config never silently breaks capture. The server already decodes Content-Encoding: zstd standard frames. * fix(capture): satisfy mypy on env compression resolution Rename the env-var lookup binding so it is not confused with the explicit-kwarg resolved value (CaptureCompression | None vs CaptureCompression). * fix(capture): avoid unused-ignore on optional zstandard import Annotate the module binding explicitly so mypy stays clean whether or not the zstandard package is installed in the dev environment. * feat(capture): route analytics through v1 submitter (capture v1, 4/6) (#704) * feat(capture): route analytics through v1 submitter when enabled Wires send_v1_batch into both send paths so capture_mode actually takes effect end to end. The consumer's async path (Consumer.request) and the client's sync path (_enqueue) now pick the analytics submitter by capture_mode: v1 -> the partial-retry send loop, v0 -> the legacy batch_post. The dedicated AI endpoint has no v1 form, so $ai_* events on it always use the legacy submitter regardless of capture_mode. Refactors Consumer.request to route via _send_analytics/_send_ai helpers, stores Client.max_retries so the sync path can pass it through, and forwards gzip/timeout/retries/historical_migration to the v1 submitter. Default is still v0, so existing callers are unaffected. Adds consumer routing-matrix tests (v0/v1, dedicated-AI split, config forwarding) and client sync-mode tests (v0 vs v1, dedicated-AI event stays legacy, analytics event uses v1). ruff/mypy clean. * feat(capture): wire capture_compression through client and consumer Resolve capture_compression once on the client (kwarg > env > legacy gzip flag > none) and thread it to the v1 submitter via the consumer and the sync path. Parameterize the capture_mode routing tests and use consistent submitter labels. * chore(capture): test $ai_* rides v1 when dedicated AI endpoint disabled * chore(capture): v1 compliance adapter + CI job (capture v1, 5/6) (#705) * chore(capture): add v1 compliance adapter mode and CI job Teaches the SDK compliance adapter to speak capture-v1 and adds a second CI job that runs the harness capture_v1 suite against it. Splits the workflow into v0 + v1 jobs, both on the 0.10.0 harness (which carries the capture_v1 suites), and adds adapter timing/debug settings for reliable test execution. * chore(capture): document capture_mode + release changeset (capture v1, 6/6) (#706) * docs(capture): document capture_mode, capture_compression, and changeset Adds the Sampo changeset for the opt-in capture_mode (v1 ingestion protocol) and capture_compression, plus an AGENTS.md section mapping capture_mode/capture_compression and their env vars to the modules and routing that implement them, the v1 invariants to preserve, and the sync_mode blocking-retry behavior. User-facing usage stays in the official docs per the README convention. * docs(capture): note v1 drop surfacing and Retry-After minimum Document the two parity behaviors added to the v1 transport: server `drop` verdicts are accumulated across attempts and surfaced via CaptureV1Error/ on_error even on a 2xx, and Retry-After acts as a minimum (max of configured backoff and Retry-After, hard-capped) rather than a replacement. * docs(capture): note the unified 30s retry backoff ceiling MAX_BACKOFF_SECONDS (30s) caps both the exponential backoff and the Retry-After clamp; update the v1 invariants note accordingly. * docs(capture): document zstd compression and private helper names
eli-r-ph
added a commit
that referenced
this pull request
Jul 6, 2026
* feat(capture): add v1 wire serialization transforms Add posthog/capture_v1.py with the pure (no-I/O) transform layer for /i/v1/analytics/events: - to_v1_event(): lifts sentinel properties into the typed options object (with the $ignore_sent_at -> disable_skew_correction rename), promotes $session_id/$window_id to top-level fields, relocates top-level $set/$set_once into properties (v1 has no top-level form), and strips $lib/$lib_version (server injects them from PostHog-Sdk-Info). Options are coerced to native JSON types or omitted, since a wrong type would 400 the whole batch. Pure: the input message is not mutated. - build_v1_batch_body(): the api_key/sent_at-free envelope with a tz-aware RFC3339 created_at. - Shared constants: path, required header names, result codes, retryable/ terminal status sets. Stacked on the capture_mode scaffolding; still inert (nothing calls these yet). * refactor(capture): store v1 option coercers as callables Hold the coercer function directly in _OPTION_SENTINELS instead of a stringly-typed name keyed through a side _COERCERS dict, removing a KeyError foot-gun and tightening the types. * refactor(capture): privatize v1 transform helpers Underscore-prefix the wire constants and transform functions and declare an empty __all__: the transforms are submitter plumbing, not public API. The user-facing surface (CaptureMode etc.) is exported elsewhere. * feat(capture): v1 transport + partial-retry send loop (capture v1, 3/6) (#703) * feat(capture): add v1 transport and partial-retry send loop Adds the HTTP transport for POST /i/v1/analytics/events alongside the pure transforms: a single Bearer-authed attempt (post_v1) with the required v1 headers, response classification (parse_v1_response), and the send loop (send_v1_batch) that resends only the events the server tags "retry", logs drops, honors Retry-After, and raises CaptureV1Error on terminal/transport failure or retry exhaustion so the consumer's existing on_error path fires unchanged. 429 is terminal in v1 (unlike v0). A 2xx with an unparseable body is terminal to avoid an infinite resend loop. A stable PostHog-Request-Id and created_at span attempts; PostHog-Attempt increments. Factors a shared gzip_compress helper out of request.post (no v0 behavior change). Still inert: nothing calls send_v1_batch until the consumer wiring PR. 74 capture_v1 tests (47 transform + 27 transport); ruff/mypy clean. * fix(capture): stabilize v1 created_at, isolate compression, quiet drops Address review of the v1 transport: - Hoist the batch created_at out of the retry loop so the envelope stays stable across attempts (only the events list and PostHog-Attempt change). - Isolate v1 request compression behind a CaptureCompression selector supporting gzip and zlib-wrapped deflate (RFC 1950), reverting the gzip_compress extraction from request.py so the v1 path owns its codecs. - Stop logging per-event drops at WARNING; a server-chosen drop on a 2xx is not a delivery failure and is already carried on CaptureV1Error for batch-level surfacing via on_error. * fix(capture): surface v1 drops and treat Retry-After as a minimum Address review of the v1 transport (#703): - Accumulate server `drop` verdicts across all attempts and raise CaptureV1Error even on a 2xx with no retry events (a success status is not full delivery) and when a later attempt clears the retries, so on_error sees every dropped uuid. Drops also ride along on the retry-exhaustion, malformed-2xx, and terminal non-2xx errors. - _backoff treats Retry-After as a minimum (max of configured backoff and Retry-After), hard-capped at 1 day, matching posthog-go/posthog-rs so a small header can't retry earlier than the schedule and a hostile one can't park the consumer thread. Adds drop-surfacing and backoff tests; regenerates public_api_snapshot. * fix(capture): unify v1 retry backoff ceiling at 30s Replace the 1-day RETRY_BACKOFF_CAP_SECONDS with a single MAX_BACKOFF_SECONDS (30s) that both caps the exponential backoff and clamps the server Retry-After, so the max retry wait is bounded and the default matches posthog-go/posthog-rs. Retry-After remains a minimum; there is no separate large cap. * refactor(capture): privatize v1 transport and compression resolver Underscore-prefix the transport layer (post_v1, parse_v1_response, send_v1_batch, response dataclasses, backoff ceiling) and the compression resolver; declare __all__ so the public surface is CaptureCompression, its env var name, and CaptureV1Error (which reaches user code via on_error callbacks). Re-export CaptureCompression at the package top level for symmetry with CaptureMode. * feat(capture): add optional zstd compression for capture v1 Add CaptureCompression.ZSTD backed by the optional zstandard package (pip install posthog[zstd]); Python has no stdlib zstd until 3.14. Explicitly requesting zstd without the package raises ValueError (fail loud at construction); requesting it via POSTHOG_CAPTURE_COMPRESSION warns and falls back so operator config never silently breaks capture. The server already decodes Content-Encoding: zstd standard frames. * fix(capture): satisfy mypy on env compression resolution Rename the env-var lookup binding so it is not confused with the explicit-kwarg resolved value (CaptureCompression | None vs CaptureCompression). * fix(capture): avoid unused-ignore on optional zstandard import Annotate the module binding explicitly so mypy stays clean whether or not the zstandard package is installed in the dev environment. * feat(capture): route analytics through v1 submitter (capture v1, 4/6) (#704) * feat(capture): route analytics through v1 submitter when enabled Wires send_v1_batch into both send paths so capture_mode actually takes effect end to end. The consumer's async path (Consumer.request) and the client's sync path (_enqueue) now pick the analytics submitter by capture_mode: v1 -> the partial-retry send loop, v0 -> the legacy batch_post. The dedicated AI endpoint has no v1 form, so $ai_* events on it always use the legacy submitter regardless of capture_mode. Refactors Consumer.request to route via _send_analytics/_send_ai helpers, stores Client.max_retries so the sync path can pass it through, and forwards gzip/timeout/retries/historical_migration to the v1 submitter. Default is still v0, so existing callers are unaffected. Adds consumer routing-matrix tests (v0/v1, dedicated-AI split, config forwarding) and client sync-mode tests (v0 vs v1, dedicated-AI event stays legacy, analytics event uses v1). ruff/mypy clean. * feat(capture): wire capture_compression through client and consumer Resolve capture_compression once on the client (kwarg > env > legacy gzip flag > none) and thread it to the v1 submitter via the consumer and the sync path. Parameterize the capture_mode routing tests and use consistent submitter labels. * chore(capture): test $ai_* rides v1 when dedicated AI endpoint disabled * chore(capture): v1 compliance adapter + CI job (capture v1, 5/6) (#705) * chore(capture): add v1 compliance adapter mode and CI job Teaches the SDK compliance adapter to speak capture-v1 and adds a second CI job that runs the harness capture_v1 suite against it. Splits the workflow into v0 + v1 jobs, both on the 0.10.0 harness (which carries the capture_v1 suites), and adds adapter timing/debug settings for reliable test execution. * chore(capture): document capture_mode + release changeset (capture v1, 6/6) (#706) * docs(capture): document capture_mode, capture_compression, and changeset Adds the Sampo changeset for the opt-in capture_mode (v1 ingestion protocol) and capture_compression, plus an AGENTS.md section mapping capture_mode/capture_compression and their env vars to the modules and routing that implement them, the v1 invariants to preserve, and the sync_mode blocking-retry behavior. User-facing usage stays in the official docs per the README convention. * docs(capture): note v1 drop surfacing and Retry-After minimum Document the two parity behaviors added to the v1 transport: server `drop` verdicts are accumulated across attempts and surfaced via CaptureV1Error/ on_error even on a 2xx, and Retry-After acts as a minimum (max of configured backoff and Retry-After, hard-capped) rather than a replacement. * docs(capture): note the unified 30s retry backoff ceiling MAX_BACKOFF_SECONDS (30s) caps both the exponential backoff and the Retry-After clamp; update the v1 invariants note accordingly. * docs(capture): document zstd compression and private helper names
eli-r-ph
added a commit
that referenced
this pull request
Jul 6, 2026
…701) * feat(capture): add capture_mode config scaffolding Introduce a CaptureMode enum (V0 legacy /batch/, V1 /i/v1/analytics/events) and resolve_capture_mode() with precedence kwarg > POSTHOG_CAPTURE_MODE env > V0. Plumb capture_mode through Client and Consumer (including fork-reinit and the module-level default client). The mode is resolved and stored but inert in this change: V0 still runs everywhere, so behavior is unchanged. First of a stacked series adding Capture V1 support. * test(capture): prove capture_mode kwarg precedence over env Set the env to the opposite mode in each precedence row so every case actually exercises kwarg-over-env, and assert an invalid kwarg raises even when a valid env value is present. * refactor(capture): make capture-mode resolver internal Rename resolve_capture_mode to _resolve_capture_mode and declare __all__ so only CaptureMode and the env var name are public API. The resolver is plumbing for Client.__init__, not a user entry point. * feat(capture): v1 wire serialization transforms (capture v1, 2/6) (#702) * feat(capture): add v1 wire serialization transforms Add posthog/capture_v1.py with the pure (no-I/O) transform layer for /i/v1/analytics/events: - to_v1_event(): lifts sentinel properties into the typed options object (with the $ignore_sent_at -> disable_skew_correction rename), promotes $session_id/$window_id to top-level fields, relocates top-level $set/$set_once into properties (v1 has no top-level form), and strips $lib/$lib_version (server injects them from PostHog-Sdk-Info). Options are coerced to native JSON types or omitted, since a wrong type would 400 the whole batch. Pure: the input message is not mutated. - build_v1_batch_body(): the api_key/sent_at-free envelope with a tz-aware RFC3339 created_at. - Shared constants: path, required header names, result codes, retryable/ terminal status sets. Stacked on the capture_mode scaffolding; still inert (nothing calls these yet). * refactor(capture): store v1 option coercers as callables Hold the coercer function directly in _OPTION_SENTINELS instead of a stringly-typed name keyed through a side _COERCERS dict, removing a KeyError foot-gun and tightening the types. * refactor(capture): privatize v1 transform helpers Underscore-prefix the wire constants and transform functions and declare an empty __all__: the transforms are submitter plumbing, not public API. The user-facing surface (CaptureMode etc.) is exported elsewhere. * feat(capture): v1 transport + partial-retry send loop (capture v1, 3/6) (#703) * feat(capture): add v1 transport and partial-retry send loop Adds the HTTP transport for POST /i/v1/analytics/events alongside the pure transforms: a single Bearer-authed attempt (post_v1) with the required v1 headers, response classification (parse_v1_response), and the send loop (send_v1_batch) that resends only the events the server tags "retry", logs drops, honors Retry-After, and raises CaptureV1Error on terminal/transport failure or retry exhaustion so the consumer's existing on_error path fires unchanged. 429 is terminal in v1 (unlike v0). A 2xx with an unparseable body is terminal to avoid an infinite resend loop. A stable PostHog-Request-Id and created_at span attempts; PostHog-Attempt increments. Factors a shared gzip_compress helper out of request.post (no v0 behavior change). Still inert: nothing calls send_v1_batch until the consumer wiring PR. 74 capture_v1 tests (47 transform + 27 transport); ruff/mypy clean. * fix(capture): stabilize v1 created_at, isolate compression, quiet drops Address review of the v1 transport: - Hoist the batch created_at out of the retry loop so the envelope stays stable across attempts (only the events list and PostHog-Attempt change). - Isolate v1 request compression behind a CaptureCompression selector supporting gzip and zlib-wrapped deflate (RFC 1950), reverting the gzip_compress extraction from request.py so the v1 path owns its codecs. - Stop logging per-event drops at WARNING; a server-chosen drop on a 2xx is not a delivery failure and is already carried on CaptureV1Error for batch-level surfacing via on_error. * fix(capture): surface v1 drops and treat Retry-After as a minimum Address review of the v1 transport (#703): - Accumulate server `drop` verdicts across all attempts and raise CaptureV1Error even on a 2xx with no retry events (a success status is not full delivery) and when a later attempt clears the retries, so on_error sees every dropped uuid. Drops also ride along on the retry-exhaustion, malformed-2xx, and terminal non-2xx errors. - _backoff treats Retry-After as a minimum (max of configured backoff and Retry-After), hard-capped at 1 day, matching posthog-go/posthog-rs so a small header can't retry earlier than the schedule and a hostile one can't park the consumer thread. Adds drop-surfacing and backoff tests; regenerates public_api_snapshot. * fix(capture): unify v1 retry backoff ceiling at 30s Replace the 1-day RETRY_BACKOFF_CAP_SECONDS with a single MAX_BACKOFF_SECONDS (30s) that both caps the exponential backoff and clamps the server Retry-After, so the max retry wait is bounded and the default matches posthog-go/posthog-rs. Retry-After remains a minimum; there is no separate large cap. * refactor(capture): privatize v1 transport and compression resolver Underscore-prefix the transport layer (post_v1, parse_v1_response, send_v1_batch, response dataclasses, backoff ceiling) and the compression resolver; declare __all__ so the public surface is CaptureCompression, its env var name, and CaptureV1Error (which reaches user code via on_error callbacks). Re-export CaptureCompression at the package top level for symmetry with CaptureMode. * feat(capture): add optional zstd compression for capture v1 Add CaptureCompression.ZSTD backed by the optional zstandard package (pip install posthog[zstd]); Python has no stdlib zstd until 3.14. Explicitly requesting zstd without the package raises ValueError (fail loud at construction); requesting it via POSTHOG_CAPTURE_COMPRESSION warns and falls back so operator config never silently breaks capture. The server already decodes Content-Encoding: zstd standard frames. * fix(capture): satisfy mypy on env compression resolution Rename the env-var lookup binding so it is not confused with the explicit-kwarg resolved value (CaptureCompression | None vs CaptureCompression). * fix(capture): avoid unused-ignore on optional zstandard import Annotate the module binding explicitly so mypy stays clean whether or not the zstandard package is installed in the dev environment. * feat(capture): route analytics through v1 submitter (capture v1, 4/6) (#704) * feat(capture): route analytics through v1 submitter when enabled Wires send_v1_batch into both send paths so capture_mode actually takes effect end to end. The consumer's async path (Consumer.request) and the client's sync path (_enqueue) now pick the analytics submitter by capture_mode: v1 -> the partial-retry send loop, v0 -> the legacy batch_post. The dedicated AI endpoint has no v1 form, so $ai_* events on it always use the legacy submitter regardless of capture_mode. Refactors Consumer.request to route via _send_analytics/_send_ai helpers, stores Client.max_retries so the sync path can pass it through, and forwards gzip/timeout/retries/historical_migration to the v1 submitter. Default is still v0, so existing callers are unaffected. Adds consumer routing-matrix tests (v0/v1, dedicated-AI split, config forwarding) and client sync-mode tests (v0 vs v1, dedicated-AI event stays legacy, analytics event uses v1). ruff/mypy clean. * feat(capture): wire capture_compression through client and consumer Resolve capture_compression once on the client (kwarg > env > legacy gzip flag > none) and thread it to the v1 submitter via the consumer and the sync path. Parameterize the capture_mode routing tests and use consistent submitter labels. * chore(capture): test $ai_* rides v1 when dedicated AI endpoint disabled * chore(capture): v1 compliance adapter + CI job (capture v1, 5/6) (#705) * chore(capture): add v1 compliance adapter mode and CI job Teaches the SDK compliance adapter to speak capture-v1 and adds a second CI job that runs the harness capture_v1 suite against it. Splits the workflow into v0 + v1 jobs, both on the 0.10.0 harness (which carries the capture_v1 suites), and adds adapter timing/debug settings for reliable test execution. * chore(capture): document capture_mode + release changeset (capture v1, 6/6) (#706) * docs(capture): document capture_mode, capture_compression, and changeset Adds the Sampo changeset for the opt-in capture_mode (v1 ingestion protocol) and capture_compression, plus an AGENTS.md section mapping capture_mode/capture_compression and their env vars to the modules and routing that implement them, the v1 invariants to preserve, and the sync_mode blocking-retry behavior. User-facing usage stays in the official docs per the README convention. * docs(capture): note v1 drop surfacing and Retry-After minimum Document the two parity behaviors added to the v1 transport: server `drop` verdicts are accumulated across attempts and surfaced via CaptureV1Error/ on_error even on a 2xx, and Retry-After acts as a minimum (max of configured backoff and Retry-After, hard-capped) rather than a replacement. * docs(capture): note the unified 30s retry backoff ceiling MAX_BACKOFF_SECONDS (30s) caps both the exponential backoff and the Retry-After clamp; update the v1 invariants note accordingly. * docs(capture): document zstd compression and private helper names
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
2 participants
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
Fourth PR in the stacked Capture V1 series (stacked on #703). This is the one that makes
capture_modeactually do something: it wiressend_v1_batch(from #703) into both send paths, so the previously-inert v1 transport is now selectable end to end. Default is stillv0, so existing callers are unaffected.Consumer.request) — refactored to route via_send_analytics/_send_ai._send_analyticspicks the submitter bycapture_mode:v1-> the partial-retrysend_v1_batch,v0-> the legacybatch_postloop._send_aialways uses the legacy submitter.Client._enqueue,sync_mode=True) — same branch: an analytics event inv1goes throughsend_v1_batch([msg]); everything else stays onbatch_post.$ai_*events routed to it always use the legacy submitter regardless ofcapture_mode. When the dedicated AI endpoint is not enabled, all events (including$ai_*) go to the single analytics destination and therefore followcapture_mode— exactly mirroring the v0 single-endpoint behavior.Supporting changes:
Client.max_retriesis now stored so the sync path can forward it, andgzip/timeout/retries/historical_migrationare forwarded to the v1 submitter so it honors the same config as v0.💚 How did you test it?
test_consumer.py— newTestConsumerCaptureModeRouting: v0 ->batch_post, v1 ->send_v1_batch, config-forwarding, dedicated-AI split (analytics-> v1 submitter /$ai_*-> legacy AI endpoint), and AI-only batch skips the v1 submitter.test_client.py— newTestClientSyncCaptureMode: v0 vs v1 sync submitter selection, config forwarding, dedicated-AI$ai_*event stays legacy, dedicated-AI analytics event uses v1.Full
test_consumer.py(25) and the new client class green;ruff format/checkclean;mypyclean onclient.py+consumer.py; regeneratedreferences/public_api_snapshot.txt.📝 Checklist
🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Authored with Cursor (Claude Opus 4.8) per the agreed plan. The routing split intentionally keeps the dedicated-AI destination on the legacy submitter — there is no v1 AI ingestion endpoint, so
capture_modeonly swaps the analytics submitter. This mirrors posthog-go, whereCaptureModelikewise governs only the analytics path.