feat(capture): add capture_mode config scaffolding (capture v1, 1/6)#701
Merged
Conversation
Contributor
|
Reviews (1): Last reviewed commit: "feat(capture): add capture_mode config s..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Contributor
posthog-python Compliance ReportDate: 2026-07-06 21:22:58 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
|
This was referenced Jun 27, 2026
eli-r-ph
force-pushed
the
capture-v1/01-config
branch
from
531fb62 to
33ebdfb
Compare
eli-r-ph
changed the base branch from
main
to
sdk-harness-audit-20260627-posthog-python
eli-r-ph
changed the base branch from
sdk-harness-audit-20260627-posthog-python
to
main
eli-r-ph
force-pushed
the
capture-v1/01-config
branch
2 times, most recently
from
b508cf9 to
b139d02
Compare
Contributor
|
Reviews (2): Last reviewed commit: "test(capture): prove capture_mode kwarg ..." | Re-trigger Greptile |
marandaneto
reviewed
Jul 6, 2026
| ) | ||
|
|
||
|
|
||
| def resolve_capture_mode( |
Member
There was a problem hiding this comment.
Suggested change
| def resolve_capture_mode( | |
| def _resolve_capture_mode( |
can we make this internal
marandaneto
approved these changes
Jul 6, 2026
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.
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.
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.
eli-r-ph
force-pushed
the
capture-v1/01-config
branch
from
b139d02 to
ce38a00
Compare
* 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
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
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
3 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
First PR in a stacked series adding Capture V1 (
POST /i/v1/analytics/events) support to the SDK, at parity with posthog-go'sCaptureModeand posthog-rs'scapture-v1.This PR is pure, inert scaffolding: it adds the capture-mode selector and threads it everywhere it will be needed, but changes no runtime behavior — V0 (legacy
/batch/) still runs on every path. Later PRs add the v1 serializer, transport, wiring, harness suite, and docs.CaptureModeenum:V0(legacy/batch/, the default) andV1(/i/v1/analytics/events)._resolve_capture_mode()(not public API) with precedence explicit kwarg >POSTHOG_CAPTURE_MODEenv >V0. OnlyCaptureModeandCAPTURE_MODE_ENV_VARare exported fromposthog.capture_mode.Client.__init__(resolved + stored asself.capture_mode), bothConsumer(...)constructions (initial + fork-reinit), and the module-level default client.Consumerstores it but does not yet act on it.💚 How did you test it?
posthog/test/test_capture_mode.py(25 cases): resolution precedence, env aliases/case/whitespace, blank-env default, unrecognized-env warn+default, invalid-kwarg raises, and plumbing toClient.capture_mode+ per-Consumerpropagation (incl. multi-thread).test_consumer,test_client,test_module,test_client_fork,test_dedicated_ai_endpoint+ the new file — 213 passed.ruff format/ruff checkclean;mypyclean on new modules; regeneratedreferences/public_api_snapshot.txt.📝 Checklist
🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Authored with Cursor (Claude Opus 4.8) following a pre-agreed, hardened implementation plan. Design decisions: enum members are Pythonic
V0/V1(not posthog-go'sLegacy/AnalyticsV1) but the env var accepts both spellings for cross-SDK consistency; the env typo path defaults defensively while an explicit bad kwarg fails fast. Mode is fully inert here by design to keep this PR a no-op for existing users and easy to review. Changeset (sampo add) and docs are intentionally deferred to the final PR so the feature releases as one entry.