feat: add crash reporting #417

ioannisj · 2025-12-22T09:07:04Z

💡 Motivation and Context

Stacked on top of #404
#skip-changelog

Adds automatic crash reporting to the PostHog iOS SDK using PLCrashReporter.
Crashes are captured and sent as $exception events with level "fatal" on the next app launch.

Crash Types Handled:

Uncaught NSExceptions
POSIX signals (e.g., SIGSEGV, SIGABRT, SIGBUS)
Mach exceptions (e.g., EXC_BAD_ACCESS, EXC_CRASH)

Implementation notes

Context Preservation: Event context (distinct_id, groups, session_id, properties) is serialized to PLCrashReporter.customData on every context change. PLCrashReporter persists this on disk. We then read this back when processing a crash so we can reconstruct event properties at the time of crash (and not at the time of processing)
Crash Report Processing: On next launch, pending crash reports are processed before enabling the crash reporter for new crashes. For now, this is a best effort, in case of failure to process we simply purge the crash report. As a future improvement we could implement a retry mechanism and a check for corrupted reports
Debug Images: Only binary images referenced in the stack trace are included
Debugger Detection: Crash handler is automatically disabled when a debugger is attached
Platform Support: iOS, macOS, tvOS only (watchOS has a stub)

Limitations

Swift crash messages: Swift crashes (like fatalError,force unwraps) appear as SIGTRAP without the actual error message (PLCrashReporter doesn't expose __crash_info section). Sentry and Bugsnag seem to have figured this out already. Left this out for now since it will require modifying PLCrashReporter
NSException chaining: Underlying errors via NSUnderlyingErrorKey are not captured (PLCrashReporter only exposes name/reason)

💚 How did you test it?

Manual testing. Will need symbolication before we know if the stack traces are healthy
Added some unit tests on utils and processing

📝 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.

marandaneto · 2025-12-22T09:57:30Z

Swift crash messages: Swift crashes (like fatalError,force unwraps) appear as SIGTRAP without the actual error message (PLCrashReporter doesn't expose __crash_info section). Sentry and Bugsnag seem to have figured this out already. Left this out for now since it will require modifying PLCrashReporter

can we create an issue for this and add to the limitation section in the docs once we have one?

marandaneto · 2025-12-22T09:58:06Z

NSException chaining: Underlying errors via NSUnderlyingErrorKey are not captured (PLCrashReporter only exposes name/reason)

do we also need to patch PLCrashReporter for this? have other folks figured this out? otherwise same as #417 (comment)

marandaneto · 2025-12-22T10:04:29Z

PostHog.podspec

  s.frameworks = 'Foundation'

+  # PLCrashReporter dependency (not available on watchOS)
+  # Using ~> 1.8 for minimum compatibility with host apps


any reason to choose this version specifically?

marandaneto · 2025-12-22T10:05:48Z

PostHog/Error Tracking/PostHogCrashReportProcessor.swift

+
+            // Add crash metadata
+            if let uuidRef = report.uuidRef {
+                properties["$crash_report_id"] = CFUUIDCreateString(nil, uuidRef) as String


what should we do with this info? should we add this to taxonomy?

marandaneto · 2025-12-22T10:27:13Z

PostHog/Error Tracking/PostHogCrashReportProcessor.swift

+                        "mach": [
+                            "exception": machException.type,
+                            "code": machException.codes.first,
+                            "subcode": machException.codes.count > 1 ? machException.codes[1] : nil,


lets skip nil values

marandaneto · 2025-12-22T10:28:42Z

PostHog/Error Tracking/PostHogCrashReportProcessor.swift

+        // MARK: - Helpers
+
+        /// Format string for zero-padded 64-bit hex addresses (e.g., "0x00007fff12345678")
+        static let hexAddressPaddedFormat = "0x%016llx"


make it private

marandaneto · 2025-12-22T10:29:53Z

PostHog/Error Tracking/PostHogCrashReportProcessor.swift

+        ]
+
+        private static func machExceptionName(_ type: UInt64) -> String {
+            machExceptionNames[type] ?? "EXC_UNKNOWN(\(type))"


probably better with EXC_UNKNOWN_X instead of EXC_UNKNOWN(X), more readable

marandaneto · 2025-12-22T10:30:38Z

PostHog/Error Tracking/PostHogCrashReporterIntegration.swift

+
+import Foundation
+
+#if os(iOS) || os(macOS) || os(tvOS)


is the manual capture also available for the 3 OSs?

marandaneto · 2025-12-22T10:31:48Z

PostHog/Error Tracking/PostHogCrashReporterIntegration.swift

+        func install(_ postHog: PostHogSDK) throws {
+            try PostHogCrashReporterIntegration.integrationInstalledLock.withLock {
+                if PostHogCrashReporterIntegration.integrationInstalled {
+                    throw InternalPostHogError(description: "Crash report integration already installed to another PostHogSDK instance.")


we can just log and bail out isntead of throwing, this would be more expensive at runtime

marandaneto · 2025-12-22T10:34:46Z

PostHog/Error Tracking/PostHogErrorTrackingConfig.swift

+    ///   as the debugger intercepts signals before the crash handler can process them.
+    ///
+    /// Default: false
+    @objc public var enableCrashHandler: Bool = false


i think we call this just autocapture on flutter? i think we should unify naming if that makes sense

marandaneto · 2025-12-22T10:36:43Z

PostHog/PostHogSDK.swift

+    /// - Parameters:
+    ///   - skipBuildProperties: When true, skips buildProperties call and uses properties as-is.
+    ///     Used by crash reporting to capture events with pre-built crash-time context.
+    func captureInternal(


this seems to be a public API now, how can we make this internal only for us? we should not expose this to customers

ioannisj added 30 commits November 14, 2025 10:10

feat: add config

28a3d2b

feat: add base error capture

f74ed8b

fix: package path

250df1a

feat: add client-side swift demangling

fd35022

feat: improve public api

660e839

feat: add binary images

530bd39

fix: swift error message

eb51920

fix:

1f053f9

feat: add PostHogStackFrame

e97cf3b

fix: synthetic

2a77d54

feat: add capture async error example

f15c3be

feat: remove swift symbol demangling

1d0a159

fix: skip top posthog frames

bc6171b

fix: remove strip symbols script

62e0a8d

fix: update sample project release config

fce9076

fix: avoid force unwrap

315530c

fix: add helper

b121d02

fix: hex constant

cc4abb8

fix: update platform

72566dd

fix: update some comments

6c836a4

fix: rename PostHogStackTrace

37f4d54

fix: default to generic mechanism type

7c137b2

feat: avoid circular chains

a78f078

fix: format

336935e

feat: base implementation

6418356

fix: minor refactor

81ea865

fix: crash report event context

2f20d82

feat: add in-app detection

a470c28

feat: add crash triggers to sample project

9262d1e

fix: cleanup debug images

5e873e3

ioannisj added 5 commits December 22, 2025 00:39

feat: exception type order

75b2a49

feat: add a note on fatalError

1e7a3a6

feat: add comment on chained exceptions

e9b9d8e

fix: format

a95db65

feat: add unit tests

e02cc58

ioannisj requested a review from a team as a code owner December 22, 2025 09:07

ioannisj requested review from a team, ablaszkiewicz, daibhin, hpouillot and oliverb123 December 22, 2025 09:07

marandaneto reviewed Dec 22, 2025

View reviewed changes

Base automatically changed from feat/error-tracking-manual-capture to feat/error-tracking December 23, 2025 09:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: add crash reporting #417

feat: add crash reporting #417

Uh oh!

ioannisj commented Dec 22, 2025

Uh oh!

marandaneto commented Dec 22, 2025

Uh oh!

marandaneto commented Dec 22, 2025

Uh oh!

marandaneto Dec 22, 2025

Uh oh!

marandaneto Dec 22, 2025

Uh oh!

marandaneto Dec 22, 2025

Uh oh!

marandaneto Dec 22, 2025

Uh oh!

marandaneto Dec 22, 2025

Uh oh!

marandaneto Dec 22, 2025

Uh oh!

marandaneto Dec 22, 2025

Uh oh!

marandaneto Dec 22, 2025

Uh oh!

marandaneto Dec 22, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: add crash reporting #417

Are you sure you want to change the base?

feat: add crash reporting #417

Uh oh!

Conversation

ioannisj commented Dec 22, 2025

💡 Motivation and Context

Crash Types Handled:

Implementation notes

Limitations

💚 How did you test it?

📝 Checklist

Uh oh!

marandaneto commented Dec 22, 2025

Uh oh!

marandaneto commented Dec 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants