Skip to content

docs: add docstrings to ExceptionCapture public methods - #1257

Merged
marandaneto merged 3 commits into
PostHog:mainfrom
mi-vault:docs/add-exception-capture-docstrings
Nov 16, 2026
Merged

marandaneto merged 3 commits into
PostHog:mainfrom
mi-vault:docs/add-exception-capture-docstrings

Conversation

@mi-vault

@mi-vault mi-vault commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Motivation and Context

ExceptionCapture is the class responsible for installing and managing process-wide sys.excepthook and threading.excepthook handlers that forward uncaught exceptions to PostHog. Its public methods (__init__, close, exception_handler, thread_exception_handler, exception_receiver, and capture_exception) had no docstrings, making it harder for contributors and integrators to understand the intent, parameters, and behaviour of each method without reading through the implementation.

This PR adds:

  • A class-level docstring describing what ExceptionCapture does and its two optional features (hook chaining and rate limiting)
  • An __init__ docstring covering all five parameters with their clamping constraints and defaults
  • Method docstrings for close, exception_handler, thread_exception_handler, exception_receiver, and capture_exception

No behaviour changes; documentation only.

How did you test it?

Existing test suite (pytest --verbose --timeout=30) passes without modification. No new tests are needed as this is a documentation-only change.

Verified with:

  • ruff format --check . (clean)
  • ruff check . (clean)
  • Manually reviewed the docstrings against the implementation for accuracy

Checklist

  • My code follows the PostHog Engineering guidelines.
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • All commits are signed with GPG (required)

Agent Context

  • Autonomy level: Human-driven (agent-assisted)
  • Tools used: Antigravity (Google DeepMind agent assistant)
  • What was decided by the human: Which file to document, which methods to cover, the wording of each docstring (reviewed and approved before commit)
  • What the agent did: Drafted docstring text based on reading the existing source code and inline comments; ran ruff checks

Add class-level docstring and per-method docstrings to ExceptionCapture,
covering __init__, close, exception_handler, thread_exception_handler,
exception_receiver, and capture_exception.

No behaviour changes — documentation only.

Signed-off-by: mi-vault <asmisharma2026@gmail.com>
@mi-vault
mi-vault requested a review from a team as a code owner November 15, 2026 16:09

@marandaneto marandaneto left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Agent-drafted and reviewed by Manoel.

Comment thread posthog/exception_capture.py Resolved
Comment thread posthog/exception_capture.py Resolved
@marandaneto
marandaneto requested a review from a team November 16, 2026 09:29
Signed-off-by: mi-vault <asmisharma2026@gmail.com>

@marandaneto marandaneto left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Agent-drafted and reviewed by Manoel.

Thanks for addressing the feedback. The bucket_size docstring now describes it as token capacity, and the exception_receiver docstring no longer claims the Django/Flask integrations use it. LGTM.

@marandaneto
marandaneto enabled auto-merge (squash) November 16, 2026 10:18
@github-actions

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 115.72 KiB/op 115.72 KiB/op <0.1% more memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Allocations per operation 1,107.61 count/op 1,107.62 count/op <0.1% more Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Time per operation 99.82 µs/op 101.41 µs/op 1.6% more time Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Idle process memory (RSS) 36.36 MiB 36.3 MiB 0.2% less memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Observed peak process memory (RSS) 38.09 MiB 38.03 MiB 0.2% less memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Process memory after settling (RSS) 38.09 MiB 38.03 MiB 0.2% less memory Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Process CPU time per operation 98.87 µs/op 100.91 µs/op 2.1% more time Not flagged
Capture and deliver events (32-byte payload, burst)
Shard: capture
Lifetime peak process memory (RSS) 40.25 MiB 40.25 MiB No observed change Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Allocated memory per operation 168.29 KiB/op 168.29 KiB/op <0.1% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Allocations per operation 1,100.66 count/op 1,100.64 count/op <0.1% fewer Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Time per operation 134.15 µs/op 135.38 µs/op 0.9% more time Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Idle process memory (RSS) 41.21 MiB 41.09 MiB 0.3% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Observed peak process memory (RSS) 46.28 MiB 46.17 MiB 0.2% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Process memory after settling (RSS) 46.28 MiB 46.17 MiB 0.2% less memory Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Process CPU time per operation 125.82 µs/op 125.52 µs/op 0.2% less time Not flagged
Capture and deliver events (4,096-byte payload, burst)
Shard: capture
Lifetime peak process memory (RSS) 51.13 MiB 51 MiB 0.3% less memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Allocated memory per operation 119.86 KiB/op 119.86 KiB/op <0.1% more memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Allocations per operation 1,147.54 count/op 1,147.56 count/op <0.1% more Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Time per operation 114.89 µs/op 113.6 µs/op 1.1% less time Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Idle process memory (RSS) 36.31 MiB 36.2 MiB 0.3% less memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Observed peak process memory (RSS) 36.39 MiB 36.29 MiB 0.3% less memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Process memory after settling (RSS) 36.39 MiB 36.29 MiB 0.3% less memory Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Process CPU time per operation 110.54 µs/op 110.44 µs/op <0.1% less time Not flagged
Capture and deliver events (32-byte payload, steady)
Shard: capture
Lifetime peak process memory (RSS) 40.25 MiB 40.25 MiB No observed change Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Allocated memory per operation 172.75 KiB/op 172.75 KiB/op <0.1% more memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Allocations per operation 1,140.43 count/op 1,140.46 count/op <0.1% more Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Time per operation 142.91 µs/op 141.44 µs/op 1% less time Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Idle process memory (RSS) 41 MiB 41.06 MiB 0.1% more memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Observed peak process memory (RSS) 41 MiB 41.06 MiB 0.1% more memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Process memory after settling (RSS) 40.99 MiB 41.05 MiB 0.1% more memory Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Process CPU time per operation 133.82 µs/op 132.1 µs/op 1.3% less time Not flagged
Capture and deliver events (4,096-byte payload, steady)
Shard: capture
Lifetime peak process memory (RSS) 41.38 MiB 41.39 MiB <0.1% more memory Not flagged
Queue an event (32-byte payload)
Shard: capture
Caller-thread CPU time per operation 73.83 µs/op 72.93 µs/op 1.2% less time Not flagged
Queue an event (32-byte payload)
Shard: capture
Time per operation 73.83 µs/op 77.8 µs/op 5.4% more time Not flagged
Queue an event (4,096-byte payload)
Shard: capture
Caller-thread CPU time per operation 75.52 µs/op 75.46 µs/op <0.1% less time Not flagged
Queue an event (4,096-byte payload)
Shard: capture
Time per operation 75.51 µs/op 76.9 µs/op 1.8% more time Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Allocated memory per operation 226.56 KiB/op 226.56 KiB/op No observed change Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Allocations per operation 2,240.44 count/op 2,240.44 count/op No observed change Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Time per operation 132.6 µs/op 133.77 µs/op 0.9% more time Not flagged
Evaluate all 10 flags
Shard: flags-scaling
Process CPU time per operation 132.58 µs/op 133.77 µs/op 0.9% 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,014.88 count/op 22,014.88 count/op No observed change Not flagged
Evaluate all 100 flags
Shard: flags-scaling
Time per operation 1.25 ms/op 1.24 ms/op 0.8% less time Not flagged
Evaluate all 100 flags
Shard: flags-scaling
Process CPU time per operation 1.25 ms/op 1.24 ms/op 0.8% less time Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Allocated memory per operation 21.69 MiB/op 21.69 MiB/op No observed change Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Allocations per operation 219,656.62 count/op 219,656.62 count/op No observed change Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Time per operation 12.63 ms/op 12.56 ms/op 0.6% less time Not flagged
Evaluate all 1,000 flags
Shard: flags-scaling
Process CPU time per operation 12.63 ms/op 12.56 ms/op 0.6% less time Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Idle process memory (RSS) 42.71 MiB 42.82 MiB 0.2% more memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Observed peak process memory (RSS) 43.1 MiB 43.15 MiB 0.1% more memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Process memory after settling (RSS) 43.1 MiB 43.15 MiB 0.1% more memory Not flagged
Evaluate 1,000 flags under concurrent load
Shard: flags-memory
Lifetime peak process memory (RSS) 42.92 MiB 43.01 MiB 0.2% more memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Idle process memory (RSS) 42.01 MiB 42.02 MiB <0.1% more memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Observed peak process memory (RSS) 42.07 MiB 42.06 MiB <0.1% less memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Process memory after settling (RSS) 42.03 MiB 41.42 MiB 1.4% less memory Not flagged
Refresh 1,000 flag definitions
Shard: flags-memory
Lifetime peak process memory (RSS) 42.46 MiB 42.35 MiB 0.3% less memory Not flagged
Evaluate one boolean flag
Shard: flags-single
Allocated memory per operation 16.63 KiB/op 16.63 KiB/op No observed change Not flagged
Evaluate one boolean flag
Shard: flags-single
Allocations per operation 164.77 count/op 164.77 count/op No observed change Not flagged
Evaluate one boolean flag
Shard: flags-single
Time per operation 8.65 µs/op 8.77 µs/op 1.4% more time Not flagged
Evaluate one boolean flag
Shard: flags-single
Process CPU time per operation 8.65 µs/op 8.77 µs/op 1.4% more time Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Allocated memory per operation 25.49 KiB/op 25.49 KiB/op No observed change Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Allocations per operation 241.28 count/op 241.28 count/op No observed change Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Time per operation 12.14 µs/op 12.11 µs/op 0.2% less time Not flagged
Evaluate a cohort-filtered flag
Shard: flags-single
Process CPU time per operation 12.14 µs/op 12.11 µs/op 0.2% less time Not flagged
Evaluate a flag (early match)
Shard: flags-single
Allocated memory per operation 40.7 KiB/op 40.7 KiB/op No observed change Not flagged
Evaluate a flag (early match)
Shard: flags-single
Allocations per operation 390.27 count/op 390.27 count/op No observed change Not flagged
Evaluate a flag (early match)
Shard: flags-single
Time per operation 16.82 µs/op 16.89 µs/op 0.4% more time Not flagged
Evaluate a flag (early match)
Shard: flags-single
Process CPU time per operation 16.82 µs/op 16.89 µs/op 0.4% more time Not flagged
Evaluate a flag (late match)
Shard: flags-single
Allocated memory per operation 61.48 KiB/op 61.48 KiB/op No observed change Not flagged
Evaluate a flag (late match)
Shard: flags-single
Allocations per operation 586.27 count/op 586.27 count/op No observed change Not flagged
Evaluate a flag (late match)
Shard: flags-single
Time per operation 24.11 µs/op 24.15 µs/op 0.2% more time Not flagged
Evaluate a flag (late match)
Shard: flags-single
Process CPU time per operation 24.11 µs/op 24.15 µs/op 0.2% more time Not flagged
Evaluate a flag (no match)
Shard: flags-single
Allocated memory per operation 60.11 KiB/op 60.11 KiB/op No observed change Not flagged
Evaluate a flag (no match)
Shard: flags-single
Allocations per operation 569.77 count/op 569.77 count/op No observed change Not flagged
Evaluate a flag (no match)
Shard: flags-single
Time per operation 22.8 µs/op 22.75 µs/op 0.2% less time Not flagged
Evaluate a flag (no match)
Shard: flags-single
Process CPU time per operation 22.79 µs/op 22.75 µs/op 0.2% less time Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Allocated memory per operation 19.93 KiB/op 19.93 KiB/op No observed change Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Allocations per operation 194.28 count/op 194.28 count/op No observed change Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Time per operation 9.77 µs/op 9.74 µs/op 0.3% less time Not flagged
Evaluate a property-filtered flag
Shard: flags-single
Process CPU time per operation 9.77 µs/op 9.74 µs/op 0.3% less time Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Allocated memory per operation 21.56 KiB/op 21.56 KiB/op No observed change Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Allocations per operation 199.78 count/op 199.78 count/op No observed change Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Time per operation 10.34 µs/op 10.25 µs/op 0.9% less time Not flagged
Evaluate a regex-filtered flag
Shard: flags-single
Process CPU time per operation 10.34 µs/op 10.25 µs/op 0.9% less time Not flagged
Evaluate a rollout flag
Shard: flags-single
Allocated memory per operation 15.79 KiB/op 15.79 KiB/op No observed change Not flagged
Evaluate a rollout flag
Shard: flags-single
Allocations per operation 154.77 count/op 154.77 count/op No observed change Not flagged
Evaluate a rollout flag
Shard: flags-single
Time per operation 8.19 µs/op 8.18 µs/op <0.1% less time Not flagged
Evaluate a rollout flag
Shard: flags-single
Process CPU time per operation 8.19 µs/op 8.18 µs/op <0.1% less time Not flagged
Evaluate a multivariate flag
Shard: flags-single
Allocated memory per operation 16.79 KiB/op 16.79 KiB/op No observed change Not flagged
Evaluate a multivariate flag
Shard: flags-single
Allocations per operation 168.77 count/op 168.77 count/op No observed change Not flagged
Evaluate a multivariate flag
Shard: flags-single
Time per operation 9.04 µs/op 9.01 µs/op 0.3% less time Not flagged
Evaluate a multivariate flag
Shard: flags-single
Process CPU time per operation 9.04 µs/op 9.01 µs/op 0.3% 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 ade1ff990b3f334a41e284ca32e3241499019d80 → 8277f4d3261a6de42508b46156220e2e7040afa1.

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.

@marandaneto
marandaneto merged commit f225118 into PostHog:main Nov 16, 2026
51 checks passed
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