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
}

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. 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 recommend that you use the Raygun Sidekick rather than tediously uploading the dSYM files yourself as described below.

Download the Raygun Sidekick right here and check out the documentation for more info.

2. Manual upload

To manually upload dSYM files, visit the Raygun dashboard, click on dSYM Center in the sidebar, then upload the dSYM file by drag ‘n dropping or using Finder.

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.

3. Automated uploading via cURL

For sending dSYMs to Raygun in other processes such as build scripts or the terminal, you can post via cURL. Below are examples of uploading a dSYM file using cURL with different authentication methods. Each needs to be substituted (including the angle brackets) with your own value as described below each code example.

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

PATH_TO_DSYM_ZIP is an absolute or relative path to a zip of you dSYM file including the file name and 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.

  1. By basic authentication
curl -H "Authorization: Basic <BASIC_AUTH_TOKEN>" -F "DsymFile=@<PATH_TO_DSYM_ZIP>" https://app.raygun.com/dashboard/<RAYGUN_APPLICATION_ID>/settings/symbols

BASIC_AUTH_TOKEN can be generated by taking your Raygun account credentials in the format username:password and then using the base 64 result.
PATH_TO_DSYM_ZIP is an absolute or relative path to a zip of you dSYM file including the file name and .zip extension.
RAYGUN_APPLICATION_ID is available in the URL of your Raygun application dashboard.

  1. By username and password
curl -u <USERNAME>:<PASSWORD> -F "DsymFile=@<PATH_TO_DSYM_ZIP>" https://app.raygun.com/dashboard/<RAYGUN_APPLICATION_ID>/settings/symbols

USERNAME and PASSWORD are your Raygun account credentials.
PATH_TO_DSYM_ZIP is an absolute or relative path to a zip of you dSYM file including the file name and .zip extension.
RAYGUN_APPLICATION_ID is available in the URL of your Raygun application dashboard.

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.