AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

instrument-error-tracking

Add PostHog error tracking to capture and monitor exceptions. Use after implementing features or reviewing PRs to ensure errors are tracked with stack traces and source maps. Also handles initial PostHog SDK setup if not yet installed.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--instrument-error-tracking at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 30

references/ios.md

AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

iOS Error Tracking installation

Canonical URL: https://posthog.com/docs/error-tracking/installation/ios

Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use https://eu.i.posthog.com instead of https://us.i.posthog.com (ingestion host), and use https://eu.posthog.com instead of https://app.posthog.com (app host for links).

On this page

Install with the wizard

Run this command in your project directory to add PostHog to your iOS project. The wizard detects your framework, installs the SDK, and sets up your first events.

npx @posthog/wizard

Or set it up manually by following the rest of this guide.

  1. 1

    Install dependency

    Required

    Install via Swift Package Manager:

    Package.swift

    dependencies: [
      .package(url: "https://github.com/PostHog/posthog-ios.git", from: "3.56.0")
    ]
    

    Or add PostHog to your Podfile:

    Podfile

    pod "PostHog", "~> 3.56"
    
  2. 2

    Configure PostHog

    Required

    Initialize PostHog in your AppDelegate:

    AppDelegate.swift

    import Foundation
    import PostHog
    import UIKit
    
    class AppDelegate: NSObject, UIApplicationDelegate {
        func application(_: UIApplication, didFinishLaunchingWithOptions _: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
            let POSTHOG_PROJECT_TOKEN = "<ph_project_token>"
            let POSTHOG_HOST = "https://us.i.posthog.com"
    
            let config = PostHogConfig(projectToken: POSTHOG_PROJECT_TOKEN, host: POSTHOG_HOST)
            PostHogSDK.shared.setup(config)
    
            return true
        }
    }
    
  3. 3

    Send events

    Recommended

    Once installed, PostHog will automatically start capturing events. You can also manually send events to test your integration:

    Swift

    PostHogSDK.shared.capture("button_clicked", properties: ["button_name": "signup"])
    
  4. 4

    Set up exception autocapture

    Recommended

    Remote configuration

    Exception autocapture can also be managed remotely via the error tracking settings.

    Platform support

    Exception autocapture is available on iOS, macOS, and tvOS only. It is not available on watchOS or visionOS due to platform limitations.

    You can still capture events manually on all platforms, including visionOS.

    You can autocapture exceptions by setting the errorTrackingConfig.autoCapture argument to true when initializing the PostHog SDK.

    Swift

    import PostHog
    
    let config = PostHogConfig(
        projectToken: "<ph_project_token>",
        host: "https://us.i.posthog.com"
    )
    config.errorTrackingConfig.autoCapture = true
    
    PostHogSDK.shared.setup(config)
    

    When enabled, this automatically captures $exception events for:

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

    Crashes are persisted to disk and sent as $exception events with level "fatal" on the next app launch.

  5. 5

    Manually capture exceptions

    Optional

    Swift Error handling

    You can manually capture exceptions using the captureException method:

    Swift

    import PostHog
    
    do {
        try FileManager.default.removeItem(at: badFileUrl)
    } catch {
        PostHogSDK.shared.captureException(error)
    }
    

    Objective-C NSException handling

    For Objective-C code that uses NSException:

    Objective-C

    @import PostHog;
    
    @try {
        [self riskyOperation];
    } @catch (NSException *exception) {
        [[PostHogSDK shared] captureExceptionWithNSException:exception properties:nil];
    }
    

    Adding custom properties

    You can add custom properties to help with debugging, grouping, and analysis:

    Swift

    do {
        try performNetworkRequest()
    } catch {
        PostHogSDK.shared.captureException(error, properties: [
            "endpoint": "/api/users",
            "retry_count": 3
        ])
    }
    

    This is helpful if you've built your own error handling logic or want to capture exceptions that are handled by your application code.

  6. 6

    Configure in-app frames

    Optional

    By default, PostHog automatically marks your app's code as "in-app" in stack traces to help you focus on your code rather than system frameworks.

    You can customize this behavior with errorTrackingConfig:

    Swift

    import PostHog
    
    let config = PostHogConfig(
        projectToken: "<ph_project_token>",
        host: "https://us.i.posthog.com"
    )
    
    // Mark additional packages as in-app
    config.errorTrackingConfig.inAppIncludes = [
        "MySharedFramework",
        "MyUtilityLib"
    ]
    
    // Exclude specific packages from being marked as in-app
    config.errorTrackingConfig.inAppExcludes = [
        "Alamofire",
        "SDWebImage"
    ]
    
    // Control default behavior for unknown packages
    config.errorTrackingConfig.inAppByDefault = true // default
    
    PostHogSDK.shared.setup(config)
    

    Configuration options:

    | Option | Description | | --- | --- | | inAppIncludes | List of package/bundle identifiers to mark as in-app (takes precedence over excludes) | | inAppExcludes | List of package/bundle identifiers to exclude from in-app | | inAppByDefault | Whether frames are considered in-app by default when origin cannot be determined |

    Default behavior:

    • Your app's bundle identifier and executable name are automatically included
    • System frameworks (Foundation, UIKit, etc.) are automatically excluded
  7. Verify error tracking

    Recommended

    Confirm events are being sent to PostHog

    Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.

    Activity feed with events

    Check for exceptions in PostHog

  8. 7

    Upload dSYMs

    Required

    Great, you're capturing exceptions! The next step is to upload dSYM files so PostHog can symbolicate your crash reports and generate accurate stack traces.

    Let's continue to the next section.

    Upload dSYMs

Limitations:

  • System symbols and frames are not symbolicated (UIKit, Foundation, etc.) (issue).
  • Swift crashes appear as SIGTRAP without the actual error message (issue).