Advanced Setup

Modify or cancel messages

The provider allows you the chance to inspect the reports before they are sent to Raygun servers. You can inspect and modify the report details or cancel the report from being sent altogether. This is done by setting a block on the shared Raygun client and will be called just before a report is sent - either automatically or manually.

Objective-C:

RaygunClient.sharedInstance.beforeSendMessage = ^BOOL(RaygunMessage * _Nonnull message) {
  if ([message.details.machineName isEqualToString:@"LOCAL_MACBOOK"]) {
    return NO; // Don't send the report
  }

  // Remove user information
  message.details.user = nil;

  return YES;
};

Swift:

RaygunClient.sharedInstance().beforeSendMessage = { (message) in
  if (message.details.error.className == "NotImplementedException") {
    return false // Don't send the report
  }

  // Remove user information
  message.details.user = nil

  return true
}

Breadcrumbs

With breadcrumbs, you can attach an accurate trail of events through your system leading up to the moment a report was generated. This helps to gain more insight into why the application crashed when it did, making prioritization of fixes much easier.

The easiest way to record a breadcrumb is by calling the recordBreadcrumb:withCategory:withLevel:withCustomData method on the RaygunClient instance. An example would be as described below.

Objective-C:

[RaygunClient.sharedInstance recordBreadcrumbWithMessage:@"User authentication succeeded"
                                           withCategory:@"Login"
                                              withLevel:RaygunBreadcrumbLevelInfo
                                         withCustomData:@{ @"UserId": @123456 }];

Swift:

RaygunClient.sharedInstance().recordBreadcrumb(message: "User authentication succeeded", category: "Login", level: RaygunBreadcrumbLevel.info, customData: ["UserId": 123456])

You can also construct your own RaygunBreadcrumb object and record it by passing it to the RaygunClient instance.

Objective-C:

RaygunBreadcrumb *breadcrumb = [RaygunBreadcrumb breadcrumbWithBlock:^(RaygunBreadcrumb *crumb) {
  crumb.message    = @"User authentication succeeded";
  crumb.category   = @"Login";
  crumb.level      = RaygunBreadcrumbLevelInfo;
  crumb.className  = @"loginAuthentication";
  crumb.methodName = @"authenticate";
  crumb.lineNumber = @123;
  crumb.customData = @{ @"UserId": @123456 };
}];

[RaygunClient.sharedInstance recordBreadcrumb:breadcrumb];

Swift:

let breadcrumb = RaygunBreadcrumb { (crumb) in
  crumb.message    = "User authentication succeeded"
  crumb.category   = "Login"
  crumb.level      = RaygunBreadcrumbLevel.info
  crumb.className  = "loginAuthentication"
  crumb.methodName = "authenticate"
  crumb.lineNumber = 123
  crumb.customData = ["UserId": @123456]
}

RaygunClient.sharedInstance().record(breadcrumb: breadcrumb)

Tags

An array of strings can be sent with each report and displayed in Raygun. This can be used to categorise errors or add additional contextual information. These tag values are also searchable in your Raygun dashboard so that you can find all error instances that you've marked with a particular tag.

Global tags

Sometimes you may want tags to be sent with all errors regardless of if they are manually or automatically reported. This can be done by setting the tags property on the shared Raygun client as described below.

Objective-C:

RaygunClient.sharedInstance.tags = @[@"GlobalTag1", @"GlobalTag2"];

Swift:

RaygunClient.sharedInstance().tags = ["GlobalTag1", "GlobalTag2"]

Per error tags

When manually reporting errors to Raygun, you can include an array of tags that will appear on that report only. 

Objective-C:

NSException *exception = [NSException exceptionWithName:@"TestException" reason:@"Something went wrong" userInfo:nil];
[RaygunClient.sharedInstance sendException:exception withTags:@[@"CustomTag1", @"CustomTag2"]];

Swift:

let exception = NSException(name: NSExceptionName.genericException, reason "Something went wrong")
RaygunClient.sharedInstance().send(exception: exception, tags: ["CustomTag1", "CustomTag2"])

Custom data

Each error can be reported with a dictionary of custom data. This data gets displayed in Raygun and can be used to record useful contextual information for debugging. Please note: currently the custom data dictionary should only include simple values such as strings and numbers.

Global custom data

Objective-C:

RaygunClient.sharedInstance.customData = @{ @"GlobalMessage" : @"Hello world", @"GlobalId" : @123 };

Swift:

RaygunClient.sharedInstance().customData = ["GlobalMessage": "Hello world", "GlobalId": 123]

Per error custom data

When manually reporting errors to Raygun, you can include a dictionary of custom data that will appear on that report only. Below is an example of how to do this. The tags array can be nil if you don't have any tags for this error.

Objective-C:

NSException *exception = [NSException exceptionWithName:@"TestException" reason:@"Something went wrong" userInfo:nil];
[RaygunClient.sharedInstance sendException:exception withTags:nil withCustomData:@{ @"CustomMessage" : @"It was me!", @"CustomMagicNumber" : @21 }];

Swift:

let exception = NSException(name: NSExceptionName.genericException, reason "Something went wrong")
RaygunClient.sharedInstance().send(exception: exception, tags: nil, customData: ["CustomMessage": "It was me!", "CustomMagicNumber": 21])

Internal logging

For debugging purposes you can set the level of logging that the provider will print to your debug console. This can be helpful to determine what information is or is not being sent to the Raygun API. The logging level can be set anytime, even before initialising the Raygun client.

Objective-C:

RaygunClient.logLevel = RaygunLoggingLevelVerbose;

Swift:

RaygunClient.logLevel = RaygunLoggingLevel.verbose

Symbolication

This provider transmits encoded reports it receives from your app as it runs on devices or emulators. To turn these reports into useful data that you can use to debug, Raygun requires your app's dSYM file. This is generated on build in Xcode and is unique to every version of your app's source. When you are finished testing locally and are deploying a new build, you need to upload the new dSYM file corresponding to that build.

Once Raygun has that build's dSYM file, the encoded reports will be turned into complete back traces, with line numbers and file names.

Uploading a dSYM file

Here are 3 options for uploading your dSYM files to your Raygun account:

1. Manual upload
   
   To manually upload dSYM files, visit the Raygun dashboard, click on dSYM Center in the sidebar, then upload the dSYM file by using the drag and drop area or selecting it through the Finder view.
   
   You can do this at any time. If you deploy a new build and Raygun receives reports without the dSYM file, it will store them ready for you to upload it. When you do, visit a report from that build and click on 'Reprocess crash report'. After a short delay, the stack trace will appear.

2. Raygun Sidekick - dSYM uploader macOS app
   
   The Raygun Sidekick is a native Mac application that sits in your Mac menu bar which will detect, zip and upload the appropriate dSYM file in just a few clicks. It is highly recommended that you use the Raygun Sidekick rather than tediously uploading the dSYM files yourself as described below.
   
   Download the Raygun Sidekick here and check out the documentation for more info.

3. Automated uploading via PowerShell or cURL
   
   For sending dSYMs to Raygun in other processes such as build scripts or the terminal, you can post via PowerShell or cURL. Below are examples of uploading a dSYM file. Each <variable> needs to be substituted (including the angle brackets) with your own value as described below.

   With PowerShell

   Invoke-WebRequest -Form @{ DsymFile = Get-Item -Path '<PATH_TO_DSYM_ZIP>'} -Method 'POST' -UseBasicParsing -Uri 'https://app.raygun.com/dashboard/<RAYGUN_APPLICATION_ID>/settings/symbols?authToken=<EXTERNAL_ACCESS_TOKEN>'
   

   or with cURL

   curl -L -F "DsymFile=@<PATH_TO_DSYM_ZIP>" https://app.raygun.com/dashboard/<RAYGUN_APPLICATION_ID>/settings/symbols?authToken=<EXTERNAL_ACCESS_TOKEN>
   

   note: Make sure to include the @ before the dSYM file path which tells cURL that the file itself is to be sent, rather than sending the path string. Missing the @ will result in an Invalid dSYM file response.

   PATH_TO_DSYM_ZIP is an absolute or relative path to a zip of your dSYM file including the file name and .zip extension.
   RAYGUN_APPLICATION_ID is available in the URL of your Raygun application dashboard. EXTERNAL_ACCESS_TOKEN can be obtained from Raygun by clicking your name in the top right corner, select "My settings" and then hit "Generate external access token" or copy it if you already have one.

Why are my stack traces not symbolicated?

There are a few reasons why your stack traces are either partially or not symbolicated at all. These include:

1. dSYM files have not been uploaded to the dSYM center in Raygun
2. dSYM files have been uploaded but are not the correct version

In the first case please ensure you have uploaded any and all dSYM files created for your application to the dSYM center. The different ways in which a dSYM file can be uploaded is described in detail above.

For the second case you need to ensure that the UUIDs listed in the dSYM center match those found in the crash report. Each crash report will list the binary images that were present when creating the report. These binary images have a UUID which corresponds to a dSYM file with the same UUID.

In order to determine if you have the appropriate dSYM files uploaded, you should take the following steps.

1. View the current dSYM files that have been uploaded to Raygun by selecting the dSYM center from the options listed under Application settings. Make a note of the UUIDs listed for each dSYM file.

2. Inspect a crash report that has not been symbolicated and switch to the Raw data tab.

3. Scroll through the JSON structure until you reach the property titled binaryImages. You can then compare the UUIDs for the binary images of the report with the UUIDs of the currently uploaded dSYMs.

If you have uploaded the appropriate dSYM files and are still experiencing issues, then please get in touch with our support team.

Version tracking

Raygun4Apple supports tracking the version of your application by setting the applicationVersion property of the Raygun client.

// Instantiate a new Raygun client
RaygunClient *raygunClient = [RaygunClient sharedInstanceWithApiKey:@"paste_your_api_key_here"];

// Set the application version
raygunClient.applicationVersion = @"1.0.0";