Skip to content

feat: let the global client set capture queue, retry and timeout options - #1281

Open
eli-r-ph wants to merge 2 commits into
mainfrom
eli/module-capture-settings
Open

eli-r-ph wants to merge 2 commits into
mainfrom
eli/module-capture-settings

Conversation

@eli-r-ph

@eli-r-ph eli-r-ph commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Public API change: five new module-level settings.

💡 Motivation and Context

An explicit Posthog client can size and tune its analytics and AI capture lanes. The global client used by posthog.capture() cannot: setup() passes none of those options, so an app on the module API gets the defaults and cannot change them.

  • Adds posthog.max_queue_size, max_retries, timeout, capture_ai_max_queue_size and capture_ai_timeout.
  • None, the default, keeps the client's own default, so nothing changes for current users.
  • setup() reads them once, when it builds the global client, like the other construction-time settings.

Open question for reviewers: the module docstring calls the global client legacy. If new settings should not land there, the alternative is to document building posthog.default_client by hand.

💚 How did you test it?

  • One test sets all five and checks each lane's queue size, timeout and retry count on the global client. It fails when setup() drops any one of them.
  • One test checks an untouched module gives the same lane settings as Posthog(...) with defaults.
  • Not run: the app-level mirror workflow.

📝 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 sampo add to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Claude Code (Claude Fable 5.2) wrote the change. flush_at, flush_interval and the compression options were left out to keep the new surface small; they can follow the same way. Retry delay is not a client option yet, so it is not here either.

🤖 Generated with Claude Code

The module-level client took none of the options an explicit `Posthog`
client has for its two capture lanes. `None` keeps the client default.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@eli-r-ph eli-r-ph self-assigned this Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

SDK performance: posthog-python

Benchmarks completed. No changes flagged for review.

Flags require at least a 5% change in the median and all six pairs agreeing on direction. This is a noise filter, not proof of a performance change or a CI gate.

View all results
Test Measurement Before PR With PR Change Assessment
Capture and deliver events (32-byte payload, burst)
Shard: capture
Managed heap after settling — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​; head:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Managed heap after settling — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​; head:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​
Capture and deliver events (32-byte payload, steady)
Shard: capture
Managed heap after settling — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​; head:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Managed heap after settling — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​; head:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​
Queue an event (32-byte payload)
Shard: capture
Allocated memory per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ Background preparation has no public completion boundary before flush; see capture.​drain for full-pipeline allocations.​; head:​ Background preparation has no public completion boundary before flush; see capture.​drain for full-pipeline allocations.​
Queue an event (32-byte payload)
Shard: capture
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ Background preparation has no public completion boundary before flush; see capture.​drain for full-pipeline allocations.​; head:​ Background preparation has no public completion boundary before flush; see capture.​drain for full-pipeline allocations.​
Queue an event (4,096-byte payload)
Shard: capture
Allocated memory per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ Background preparation has no public completion boundary before flush; see capture.​drain for full-pipeline allocations.​; head:​ Background preparation has no public completion boundary before flush; see capture.​drain for full-pipeline allocations.​
Queue an event (4,096-byte payload)
Shard: capture
Allocations per operation — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ Background preparation has no public completion boundary before flush; see capture.​drain for full-pipeline allocations.​; head:​ Background preparation has no public completion boundary before flush; see capture.​drain for full-pipeline allocations.​
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Managed heap after settling — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​; head:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​
Refresh 1,000 flag definitions
Shard: flags-memory
Managed heap after settling — — — unavailable; base:​ unsupported; head:​ unsupported; base:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​; head:​ CPython has no uninstrumented total managed-heap byte counter; tracing would distort this RSS pass.​
Capture and deliver events (32-byte payload, burst)
Shard: capture
Allocated memory per operation 133.67 KiB/op 133.67 KiB/op No observed change Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Allocations per operation 1,345.51 count/op 1,345.51 count/op No observed change Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Time per operation 78.19 µs/op 78.32 µs/op 0.2% more time Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Idle process memory (RSS) 37.6 MiB 37.63 MiB 0.1% more memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Observed peak process memory (RSS) 40.04 MiB 40.08 MiB 0.1% more memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Process memory after settling (RSS) 40.04 MiB 40.08 MiB 0.1% more memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Process CPU time per operation 82.35 µs/op 81 µs/op 1.6% less time Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Lifetime peak process memory (RSS) 40.19 MiB 40.28 MiB 0.2% more memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Allocated memory per operation 185.75 KiB/op 185.75 KiB/op No observed change Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Allocations per operation 1,337.51 count/op 1,337.51 count/op No observed change Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Time per operation 102.04 µs/op 102.2 µs/op 0.2% more time Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Idle process memory (RSS) 41.28 MiB 41.26 MiB <0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Observed peak process memory (RSS) 47.06 MiB 47.04 MiB <0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Process memory after settling (RSS) 47.06 MiB 47.04 MiB <0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Process CPU time per operation 98.25 µs/op 99.11 µs/op 0.9% more time Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Lifetime peak process memory (RSS) 51.44 MiB 51.44 MiB <0.1% more memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Allocated memory per operation 138.73 KiB/op 138.73 KiB/op <0.1% less memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Allocations per operation 1,390.29 count/op 1,390.28 count/op <0.1% fewer Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Time per operation 89.66 µs/op 89.2 µs/op 0.5% less time Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Idle process memory (RSS) 37.54 MiB 37.58 MiB <0.1% more memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Observed peak process memory (RSS) 37.72 MiB 37.74 MiB <0.1% more memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Process memory after settling (RSS) 37.72 MiB 37.74 MiB <0.1% more memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Process CPU time per operation 91.55 µs/op 91.22 µs/op 0.4% less time Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Lifetime peak process memory (RSS) 40.18 MiB 40.18 MiB No observed change Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Allocated memory per operation 190.9 KiB/op 190.9 KiB/op <0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Allocations per operation 1,382.19 count/op 1,382.18 count/op <0.1% fewer Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Time per operation 106.83 µs/op 106.77 µs/op <0.1% less time Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Idle process memory (RSS) 41.09 MiB 41.14 MiB 0.1% more memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Observed peak process memory (RSS) 41.55 MiB 41.58 MiB <0.1% more memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Process memory after settling (RSS) 41.15 MiB 41.19 MiB <0.1% more memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Process CPU time per operation 104.91 µs/op 103.33 µs/op 1.5% less time Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Lifetime peak process memory (RSS) 41.5 MiB 41.54 MiB <0.1% more memory Not flagged
Queue an event (32-byte payload)
Shard: capture
Caller-thread CPU time per operation 57.87 µs/op 57.69 µs/op 0.3% less time Not flagged
Queue an event (32-byte payload)
Shard: capture
Time per operation 57.87 µs/op 57.7 µs/op 0.3% less time Not flagged
Queue an event (4,096-byte payload)
Shard: capture
Caller-thread CPU time per operation 57.81 µs/op 58 µs/op 0.3% more time Not flagged
Queue an event (4,096-byte payload)
Shard: capture
Time per operation 57.81 µs/op 58 µs/op 0.3% more time Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Allocated memory per operation 225.43 KiB/op 225.43 KiB/op No observed change Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Allocations per operation 2,279.42 count/op 2,279.42 count/op No observed change Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Time per operation 82.66 µs/op 83.59 µs/op 1.1% more time Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Process CPU time per operation 82.67 µs/op 83.59 µs/op 1.1% more time Not flagged
Evaluate all 100 flags
Shard: flags-scaling
Allocated memory per operation 2.17 MiB/op 2.17 MiB/op No observed change Not flagged
Evaluate all 100 flags
Shard: flags-scaling
Allocations per operation 22,413.69 count/op 22,413.69 count/op No observed change Not flagged
Evaluate all 100 flags
Shard: flags-scaling
Time per operation 774.61 µs/op 774.78 µs/op <0.1% more time Not flagged
Evaluate all 100 flags
Shard: flags-scaling
Process CPU time per operation 774.67 µs/op 774.82 µs/op <0.1% more time Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Allocated memory per operation 21.63 MiB/op 21.63 MiB/op No observed change Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Allocations per operation 223,655.44 count/op 223,655.44 count/op No observed change Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Time per operation 7.72 ms/op 7.74 ms/op 0.3% more time Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Process CPU time per operation 7.72 ms/op 7.74 ms/op 0.3% more time Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Idle process memory (RSS) 43.95 MiB 43.85 MiB 0.2% less memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Observed peak process memory (RSS) 44.2 MiB 44.19 MiB <0.1% less memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Process memory after settling (RSS) 44.2 MiB 44.19 MiB <0.1% less memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Lifetime peak process memory (RSS) 43.96 MiB 43.99 MiB <0.1% more memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Idle process memory (RSS) 43.02 MiB 42.93 MiB 0.2% less memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Observed peak process memory (RSS) 43.03 MiB 42.94 MiB 0.2% less memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Process memory after settling (RSS) 43.03 MiB 42.94 MiB 0.2% less memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Lifetime peak process memory (RSS) 42.81 MiB 43.11 MiB 0.7% more memory Not flagged
Evaluate one boolean flag
Shard: flags-single
Allocated memory per operation 15.74 KiB/op 15.74 KiB/op No observed change Not flagged
Evaluate one boolean flag
Shard: flags-single
Allocations per operation 162.77 count/op 162.77 count/op No observed change Not flagged
Evaluate one boolean flag
Shard: flags-single
Time per operation 8.17 µs/op 8.21 µs/op 0.5% more time Not flagged
Evaluate one boolean flag
Shard: flags-single
Process CPU time per operation 8.17 µs/op 8.21 µs/op 0.5% more time Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Allocated memory per operation 24.6 KiB/op 24.6 KiB/op No observed change Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Allocations per operation 239.28 count/op 239.28 count/op No observed change Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Time per operation 11.51 µs/op 11.56 µs/op 0.5% more time Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Process CPU time per operation 11.51 µs/op 11.57 µs/op 0.5% more time Not flagged
Evaluate a flag (early match)
Shard: flags-single
Allocated memory per operation 39.81 KiB/op 39.81 KiB/op No observed change Not flagged
Evaluate a flag (early match)
Shard: flags-single
Allocations per operation 388.27 count/op 388.27 count/op No observed change Not flagged
Evaluate a flag (early match)
Shard: flags-single
Time per operation 16.39 µs/op 16.35 µs/op 0.3% less time Not flagged
Evaluate a flag (early match)
Shard: flags-single
Process CPU time per operation 16.39 µs/op 16.35 µs/op 0.3% less time Not flagged
Evaluate a flag (late match)
Shard: flags-single
Allocated memory per operation 60.59 KiB/op 60.59 KiB/op No observed change Not flagged
Evaluate a flag (late match)
Shard: flags-single
Allocations per operation 584.27 count/op 584.27 count/op No observed change Not flagged
Evaluate a flag (late match)
Shard: flags-single
Time per operation 23.49 µs/op 23.59 µs/op 0.4% more time Not flagged
Evaluate a flag (late match)
Shard: flags-single
Process CPU time per operation 23.49 µs/op 23.59 µs/op 0.4% more time Not flagged
Evaluate a flag (no match)
Shard: flags-single
Allocated memory per operation 59.22 KiB/op 59.22 KiB/op No observed change Not flagged
Evaluate a flag (no match)
Shard: flags-single
Allocations per operation 567.77 count/op 567.77 count/op No observed change Not flagged
Evaluate a flag (no match)
Shard: flags-single
Time per operation 22.27 µs/op 22.21 µs/op 0.3% less time Not flagged
Evaluate a flag (no match)
Shard: flags-single
Process CPU time per operation 22.27 µs/op 22.21 µs/op 0.3% less time Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Allocated memory per operation 19.04 KiB/op 19.04 KiB/op No observed change Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Allocations per operation 192.27 count/op 192.27 count/op No observed change Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Time per operation 9.32 µs/op 9.19 µs/op 1.3% less time Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Process CPU time per operation 9.32 µs/op 9.19 µs/op 1.3% less time Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Allocated memory per operation 20.66 KiB/op 20.66 KiB/op No observed change Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Allocations per operation 197.77 count/op 197.77 count/op No observed change Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Time per operation 9.85 µs/op 9.74 µs/op 1.1% less time Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Process CPU time per operation 9.85 µs/op 9.75 µs/op 1.1% less time Not flagged
Evaluate a rollout flag
Shard: flags-single
Allocated memory per operation 14.89 KiB/op 14.89 KiB/op No observed change Not flagged
Evaluate a rollout flag
Shard: flags-single
Allocations per operation 152.77 count/op 152.77 count/op No observed change Not flagged
Evaluate a rollout flag
Shard: flags-single
Time per operation 7.71 µs/op 7.7 µs/op <0.1% less time Not flagged
Evaluate a rollout flag
Shard: flags-single
Process CPU time per operation 7.71 µs/op 7.7 µs/op <0.1% less time Not flagged
Evaluate a multivariate flag
Shard: flags-single
Allocated memory per operation 15.9 KiB/op 15.9 KiB/op No observed change Not flagged
Evaluate a multivariate flag
Shard: flags-single
Allocations per operation 166.77 count/op 166.77 count/op No observed change Not flagged
Evaluate a multivariate flag
Shard: flags-single
Time per operation 8.57 µs/op 8.51 µs/op 0.7% less time Not flagged
Evaluate a multivariate flag
Shard: flags-single
Process CPU time per operation 8.57 µs/op 8.51 µs/op 0.7% less time Not flagged

Values are medians of paired measurements. Not flagged does not mean unchanged. Unavailable means a measurement could not be provided, not zero. Estimated allocation measurements retain their instrumentation uncertainty. RSS measures the whole process, not just SDK allocations; observed peaks are sampled checkpoints. Paired ranges in the diagnostics describe variability, not confidence intervals.

Each shard uses its own runner; compare Before PR against With PR within a row, not across shards.

Compared 5994ff313c6dfb0cbbe3d29f367fb3b7c0a80a94 → 2a076780b3807f2220b9654a319282936ffe7a3a.

Full report and diagnostics

102 metric rows; 102 rows shown in all results. Omitted or shortened data remain in comparison.json, including per-runner environments, resource limits, measurement methods, samples and checkpoints.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@eli-r-ph
eli-r-ph marked this pull request as ready for review November 19, 2026 19:38
@eli-r-ph
eli-r-ph requested a review from a team as a code owner November 19, 2026 19:38
@veria-ai

veria-ai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

PR overview

No security issues were found in this pull request.

Reviews

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.

1 participant