feat: walk exception cause chains

[hpouillot]

💡 Motivation and Context

Capture the full Ruby exception.cause chain instead of only the outermost exception, preserving parent linkage and mechanism metadata for each entry. This also lets automatic Rails integrations set the mechanism type and handled flag for captured exceptions.

This is the first PR split out of the broader error-tracking capture improvements.

💚 How did you test it?

Not run successfully locally. bundle exec rspec spec/posthog/exception_capture_spec.rb spec/posthog/client_spec.rb spec/posthog/rails/exception_mechanism_spec.rb failed because the rspec executable is not installed in the local bundle.

📝 Checklist

• 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 pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Implemented with Pi. The original combined error-tracking capture change was split so this PR only covers cause-chain walking and capture mechanism metadata; the path-stabilization change is left for a follow-up PR.

[github-actions]

posthog-ruby Compliance Report

Date: 2026-07-02 19:11:26 UTC
Duration: 97977ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	10ms
Format Validation.Event Has Uuid	✅	106ms
Format Validation.Event Has Lib Properties	✅	109ms
Format Validation.Distinct Id Is String	✅	106ms
Format Validation.Token Is Present	✅	107ms
Format Validation.Custom Properties Preserved	✅	107ms
Format Validation.Event Has Timestamp	✅	108ms
Retry Behavior.Retries On 503	✅	5309ms
Retry Behavior.Does Not Retry On 400	✅	2108ms
Retry Behavior.Does Not Retry On 401	✅	2109ms
Retry Behavior.Respects Retry After Header	✅	8016ms
Retry Behavior.Implements Backoff	✅	15511ms
Retry Behavior.Retries On 500	✅	5213ms
Retry Behavior.Retries On 502	✅	5212ms
Retry Behavior.Retries On 504	✅	5212ms
Retry Behavior.Max Retries Respected	✅	15515ms
Deduplication.Generates Unique Uuids	✅	113ms
Deduplication.Preserves Uuid On Retry	✅	5213ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10317ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5215ms
Deduplication.No Duplicate Events In Batch	✅	112ms
Deduplication.Different Events Have Different Uuids	✅	108ms
Compression.Sends Gzip When Enabled	✅	106ms
Batch Format.Uses Proper Batch Structure	✅	108ms
Batch Format.Flush With No Events Sends Nothing	✅	5ms
Batch Format.Multiple Events Batched Together	✅	112ms
Error Handling.Does Not Retry On 403	✅	2109ms
Error Handling.Does Not Retry On 413	✅	2109ms
Error Handling.Retries On 408	✅	5212ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	109ms
Request Payload.Flags Request Uses V2 Query Param	✅	108ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	110ms
Request Payload.Flags Request Omits Authorization Header	✅	107ms
Request Payload.Token In Flags Body Matches Init	✅	107ms
Request Payload.Groups Round Trip	✅	107ms
Request Payload.Groups Default To Empty Object	✅	107ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	107ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	107ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	107ms
Request Lifecycle.No Flags Request On Init Alone	✅	4ms
Request Lifecycle.No Flags Request On Normal Capture	✅	106ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	111ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	106ms
Retry Behavior.Retries Flags On 502	✅	210ms
Retry Behavior.Retries Flags On 504	✅	255ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	109ms

[greptile-apps]

_{Reviews (1): Last reviewed commit: "feat: walk exception cause chains" | Re-trigger Greptile}

[cat-ph]

interesting, I thought we had this, thanks for adding!

looks good, maybe warrants a stamp from @PostHog/team-client-libraries too because of the public api change but I think it's additive only and shouldn't break existing users

[ablaszkiewicz]

🚀