Advanced Setup

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.


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;


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.


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


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

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


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


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

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

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.

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.


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


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

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


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


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

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.


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


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

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.


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


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

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.


RaygunClient.logLevel = RaygunLoggingLevelVerbose;


RaygunClient.logLevel = RaygunLoggingLevel.verbose

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.

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 '<RAYGUN_APPLICATION_ID>/settings/symbols?authToken=<EXTERNAL_ACCESS_TOKEN>'

    or with cURL

    curl -F "DsymFile=@<PATH_TO_DSYM_ZIP>"<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.

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.

note: A crash report can only be symbolicated with a dSYM file whose UUID matches an UUID of a binary image listed in the report.

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. Sidekick Mac Menu Bar Location

  2. Inspect a crash report that has not been symbolicated and switch to the Raw data tab. Sidekick Mac Menu Bar Location

  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. Sidekick Mac Menu Bar Location

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

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:@"_INSERT_API_KEY_"];

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