Swiftpack.co - Package - backtrace-labs/backtrace-cocoa

Backtrace

Backtrace's integration with iOS and macOS applications allows customers to capture and report handled and unhandled exceptions to their Backtrace instance, instantly offering the ability to prioritise and debug software errors.

Supported platforms Language: Swift 4 Language: Objecive-C CocoaPods compatible License: MIT

Minimal usage

Create the BacktraceClient using init(credentials:) initializer and then send error/exception just by calling method send:

  • Swift
import UIKit
import Backtrace

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    var window: UIWindow?
    
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
                     
        let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!,
                                                        token: "token")
        BacktraceClient.shared = try? BacktraceClient(credentials: backtraceCredentials)

        do {
            try throwingFunc()
        } catch {
            BacktraceClient.shared?.send { (result) in
                print(result)
            }
        }

        return true
    }
}
  • Objective-C
#import "AppDelegate.h"
@import Backtrace;

@interface AppDelegate ()

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    BacktraceCredentials *credentials = [[BacktraceCredentials alloc]
                                         initWithEndpoint: [NSURL URLWithString: @"https://backtrace.io"]
                                         token: @"token"];
    BacktraceClient.shared = [[BacktraceClient alloc] initWithCredentials: credentials error: nil];

    // sending NSException
    @try {
        NSArray *array = @[];
        NSObject *object = array[1]; // will throw exception
    } @catch (NSException *exception) {
        [[BacktraceClient shared] sendWithException: exception completion:^(BacktraceResult * _Nonnull result) {
            NSLog(@"%@", result);
        }];
    } @finally {

    }

    //sending NSError
    NSError *error = [NSError errorWithDomain: @"backtrace.domain" code: 100 userInfo: @{}];
    [[BacktraceClient shared] sendWithCompletion:^(BacktraceResult * _Nonnull result) {
        NSLog(@"%@", result);
    }];

    return YES;
}

@end

Features Summary

  • Light-weight client library written in Swift with full Objective-C support that quickly submits exceptions/errors and crashes to your Backtrace dashboard includes:
    • system metadata,
    • machine metadata,
    • signal metadata,
    • exception metadata,
    • thread metadata,
    • process metadata.
  • Supports iOS and macOS platforms.
  • Swift first protocol-oriented framework.

Installation

via CocoaPods

To use CocoaPods just add this to your Podfile:

pod 'Backtrace'

Note: It is required to specify use_frameworks! in your Podfile.

Documentation

Register with Backtrace credentials

Register to Backtrace services using provided submission url (see: What is a submission url?) and token (see: What is a submission token?).

  • Swift
BacktraceClient.shared = try? BacktraceClient(credentials: BacktraceCredentials)
  • Objective-C
BacktraceClient.shared = [[BacktraceClient alloc] initWithCredentials: BacktraceCredentials error: error];

Backtrace client configuration

For more advanced usage of BacktraceClient, you can supply BacktraceClientConfiguration as a parameter. See the following example:

let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!,
                                                        token: "token")
let configuration = BacktraceClientConfiguration(credentials: backtraceCredentials,
                                                 dbSettings: BacktraceDatabaseSettings(),
                                                 reportsPerMin: 10)
BacktraceClient.shared = try? BacktraceClient(configuration: configuration)

Database settings

BacktraceClient allows you to customize the initialization of BacktraceDatabase for local storage of error reports by supplying a BacktraceDatabaseSettings parameter, as follows:

let backtraceCredentials = BacktraceCredentials(endpoint: URL(string: "https://backtrace.io")!,
                                                        token: "token")
let backtraceDatabaseSettings = BacktraceDatabaseSettings()
backtraceDatabaseSettings.maxRecordCount = 1000
backtraceDatabaseSettings.maxDatabaseSize = 10
backtraceDatabaseSettings.retryInterval = 5
backtraceDatabaseSettings.retryLimit = 3
backtraceDatabaseSettings.retryBehaviour = RetryBehaviour.interval
backtraceDatabaseSettings.retryOrder = RetryOder.queue
let backtraceConfiguration = BacktraceClientConfiguration(credentials: backtraceCredentials,
                                                          dbSettings: backtraceDatabaseSettings,
                                                          reportsPerMin: 10)
BacktraceClient.shared = try? BacktraceClient(configuration: backtraceConfiguration)

Events handling

BacktraceClient allows you to subscribe for events produced before and after sending error report:

  • Swift
BacktraceClient.shared?.delegate = self

func willSend(_ report: BacktraceCrashReport) -> (BacktraceCrashReport)
func willSendRequest(_ request: URLRequest) -> URLRequest
func serverDidFail(_ error: Error)
func serverDidResponse(_ result: BacktraceResult)
func didReachLimit(_ result: BacktraceResult)

User attributes

You can add custom user attributes that should be send alongside crash and erros/exceptions:

  • Swift
BacktraceClient.shared?.userAttributes = ["foo": "bar", "testing": true]

Sending an error report

Registered BacktraceClient will be able to send an crash reports. Error report is automatically generated based.

Sending Error/NSError

  • Swift
@objc func send(completion: ((BacktraceResult) -> Void))
  • Objective-C
 - (void) sendWithCompletion: (void (^)(BacktraceResult * _Nonnull)) completion;

Sending NSException

  • Swift
@objc func send(exception: NSException, completion: ((BacktraceResult) -> Void))
  • Objective-C
 - (void) sendWithException: NSException completion: (void (^)(BacktraceResult * _Nonnull)) completion;

FAQ

Missing dSYM files

Make sure your project is configured to generate the debug symbols:

  • Go to your project target's build settings: YourTarget -> Build Settings.
  • Search for Debug Information Format.
  • Select DWARF with dSYM File. alt text

Finding dSYMs while building project

  • Build the project.
  • Build products and dSYMs are placed into the Products directory. alt text alt text
  • Zip all the dSYM files and upload to Backtrace services (see: Symbolification)

Finding dSYMs while archiving project

  • Archive the project.
  • dSYMs are placed inside of an .xcarchive of your project.
  • Open Xcode -> Window -> Organizer
  • Click on archive and select Show in Finder alt text
  • Click on Show Package Contents alt text
  • Search for dSYMs directory alt text
  • Zip all the dSYM files and upload to Backtrace services (see: Symbolification)

Github

link
Stars: 0
Help us keep the lights on

Dependencies

Used By

Total: 0

Releases

1.3.0 - Mar 5, 2019

  • Add support for default attributes
  • Add support for user-defined attributes
  • Handle saving all kind of attributes on crash-time
  • Simplified library API
  • Add more customization for BacktraceClient implementation