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?

1.8.0 is the earliest version that supports saving custom data along with the crash report (PLCrashReporter.customData), which we use to persist context at crash time so we can accurately rebuild all the event properties on subsequent app launches. So minimum version that has the features we need

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

PostHog/ErrorTracking/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?

This is a uuid that PLCrashReport generates. It's crash metadata, so I figured we wouldn't want to lose it and it won't hurt including it, even though tbh I can't think of any uses of it. Maybe deduplication of reports BE side but that's highly unlikely since we delete the crash report once processed. I'm okay removing this

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

PostHog/ErrorTracking/PostHogCrashReportProcessor.swift

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


lets skip nil values

nil values are removed with .compactMapValues { $0 } below, for both "meta" and "mach" keys. Not super efficient but the number of keys is really small here so negligible I believe

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

agreed, done

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

PostHog/ErrorTracking/PostHogErrorTrackingAutoCaptureIntegration.swift

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


is the manual capture also available for the 3 OSs?

No, manual capture is available on watchOS as well.
For this class, we have fallback stub implementation for watchOS, which I think works well. To be consistent on the public API, however, I'll mark this config unavailable for watchOS

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

PostHog/ErrorTracking/PostHogErrorTrackingAutoCaptureIntegration.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

This is a pattern we use for other integrations as well. We catch on install step and log in PostHogSDK. We could change the signature of this method to return a truthy for success or failure instead, but I'll skip for this PR to keep the scope down

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

flutter uses captureX for different error types, but Android and RN do use autoCapture.
Updated config to autoCapture and integration to PostHogErrorTrackingAutoCaptureIntegration for consistency

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

This is an internal method that accepts an additional shouldBuildProperties: Bool parameter (used internally when capturing an exception event). I think the public API remains unchanged

# Conflicts: # PostHog.xcodeproj/project.pbxproj # PostHog/ErrorTracking/Models/PostHogBinaryImageInfo.swift # PostHog/ErrorTracking/PostHogErrorTrackingConfig.swift # PostHog/ErrorTracking/PostHogExceptionProcessor.swift # PostHog/ErrorTracking/Utils/PostHogDebugImageProvider.swift # PostHog/PostHogSDK.swift # PostHogExample/ContentView.swift # PostHogExample/ExceptionHandler.h # PostHogExample/ExceptionHandler.m

ioannisj · 2026-01-30T11:55:15Z

Build is green locally but fails in CI, looking into it

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

ioannisj added 10 commits January 30, 2026 03:13

fix: rename config option and integration

b0e8fb3

Merge branch 'main' into feat/error-tracking-autocapture

931a5f0

fix: format

40b3c50

fix: folder structure

2d39504

fix:

6c78106

fix: mark autoCapture unavailable on watchOS and visionOS

a993c53

fix: tvOS mach unavailable

786e3d1

fix: project

a0bcd80

fix: temp disable swiftlint rule

8df74ba

ioannisj added 2 commits January 30, 2026 16:26

fix: ci

ab5dcaf

fix: build

5f9f049

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!

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!

ioannisj commented Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants