feat(exception-capture): implement thread-safe fixed-window rate limiting with post-limit sampling

[mishrak5j]

🚀 Description

Implements client-side exception rate limiting to resolve the open TODO
in posthog/exception_capture.py. Introduces a dedicated ExceptionRateLimiter
that clamps exception traffic in local memory before any network transmission.

---

🛠️ Design Architecture

Dual-stage filtering pipeline:

[ Unhandled Exception Caught ]
│
▼
Stage 1: ExceptionRateLimiter (Fixed Window + Heartbeat)
├─► Acquires thread lock
├─► Checks window expiry, resets if elapsed
├─► count <= max ──► Allow
└─► count > max ──► Allow every Nth (heartbeat signal, count % post_limit_every == 0)
│
▼ (passed Stage 1)
Stage 2: Sampling (lock-free)
└─► random.random() > sample_rate ──► Drop
│
▼ (passed Stage 2)
[ Client Outbound Ingestion Queue ]

---

⚙️ New Client Configuration Parameters

Parameter	Default	Description
exception_capture_max_per_window	100	Max exceptions before heartbeat kicks in
exception_capture_window_seconds	60.0	Rolling window duration in seconds
exception_capture_sample_rate	1.0	Fraction of exceptions to forward (0.0–1.0)

---

🧪 Tests Added

• test_allows_within_limit_and_handles_heartbeat — verifies first N pass, then 1-in-N heartbeat
• test_window_resets_counters_cleanly — verifies counter resets after window expiry
• test_invalid_parameters_raise_value_errors — verifies bad config raises ValueError
• test_post_every_one_allows_all_events_after_limit — verifies post_limit_every=1 bypasses throttle

---

📝 Checklist

• I reviewed the submitted code
• I added tests to verify the changes
• I updated the docs if needed
• Added changelog entry via sampo add

⚠️ Breaking Changes

None at runtime — new client config params use getattr with safe defaults.
Existing Client instances without these attributes will behave identically to before.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Introduces client-side exception capture throttling to prevent flooding PostHog with repeated exception events.

Changes:

• Added a thread-safe fixed-window ExceptionRateLimiter with post-limit “heartbeat” sampling.
• Integrated the rate limiter (and an additional sample-rate gate) into exception capture flow.
• Added unit tests validating rate limiter behavior, window resets, and parameter validation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
posthog/rate_limiter.py	Adds the ExceptionRateLimiter implementation used to throttle exception capture.
posthog/test/test_rate_limiter.py	Adds unit coverage for rate limit behavior and configuration validation.
posthog/exception_capture.py	Wires the limiter into exception capture and adds probabilistic sampling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[greptile-apps]

Comments Outside Diff (1)

1. posthog/exception_capture.py, line 18-21 (link)

   The TODO this PR was introduced to resolve still remains. Since rate limiting is now implemented, the stale comment should be removed to avoid confusing future readers.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: posthog/exception_capture.py
   Line: 18-21
   
   Comment:
   The TODO this PR was introduced to resolve still remains. Since rate limiting is now implemented, the stale comment should be removed to avoid confusing future readers.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Prompt To Fix All With AI

Fix the following 3 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 3
posthog/exception_capture.py:18-21
The TODO this PR was introduced to resolve still remains. Since rate limiting is now implemented, the stale comment should be removed to avoid confusing future readers.

```suggestion
class ExceptionCapture:
    log = logging.getLogger("posthog")
```

### Issue 2 of 3
posthog/rate_limiter.py:75-83
`_get_state_for_tests` is not called by any test in `test_rate_limiter.py` and reads shared state without holding `_lock`, making it inconsistent under concurrent access. Since the tests drive the limiter entirely through `should_capture()`, this method is purely superfluous — it should be removed.

```suggestion

```

### Issue 3 of 3
posthog/test/test_rate_limiter.py:82-94
**Prefer parameterised tests for validation cases**

The team convention is to use parameterised tests. `test_invalid_parameters_raise_value_errors` groups four independent input/error pairs inside one function body, which means a failure in an early `pytest.raises` block masks the remaining cases. Using `@pytest.mark.parametrize` with `(kwargs, match)` tuples makes each case independently reportable and aligns with the project style.

_{Reviews (1): Last reviewed commit: "feat: add client-side fixed window excep..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

[marandaneto]

@PostHog/team-error-tracking do we need this? we dont have that in any other SDK i think (for exceptions at least)