Skip to content

Troubleshooting

SDK Initialization Exception Verification

In the Debug environment, after configuring the Guance SDK and running the application for the first time, please check your debugger console in Xcode. The SDK will use assertions to verify the correctness of multiple configurations and crash if there are errors, outputting relevant warnings.

eg: If the SDK is configured without setting the datakit metrics write address, the program will crash and output a warning⚠️ in the console.

*** Assertion failure in +[FTMobileAgent startWithConfigOptions:], FTMobileAgent.m:53
*** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'Please set the datakit metrics write address'

Enable Debug Mode

It is recommended to enable the FTMobileConfig option enableSDKDebugLog = YES in the Debug environment and disable it in the Release environment. The SDK debug logs are prefixed with [FTLog] and can be filtered using [FTLog].

Note: If the scheme is set to OS_ACTIVITY_MODE=disable, the SDK debug logs will not be output properly. It is recommended to disable this setting during debugging.

It is recommended to disable Debug mode when releasing the Release version

Log Example

Data Synchronization

// Below are normal synchronization logs
[FTLog][INFO] -[FTTrackDataManger flushWithEvents:type:] [line 143] ↵
                                                Start reporting events (Number of events reported this time:2)
[FTLog][INFO] -[FTRequestLineBody getRequestBodyWithEventArray:] [line 149]
Upload Datas Type:RUM
Line RequestDatas:
...... datas ......
[FTLog][INFO] -[FTTrackDataManger flushWithEvents:type:]_block_invoke [line 157] ↵
                                                Upload Response statusCode : 200

// In versions prior to 1.3.10, `Upload Response statusCode : 200` would not be printed,
// You can check the console for error logs; no error logs indicate successful upload.
// Error logs:
// Network failure: .....` or Server anomaly Try again later ......

In versions prior to 1.3.10, Upload Response statusCode : 200 would not be printed. You can check the console for error logs; no error logs indicate successful upload.

Error logs: Network failure: ...... or Server anomaly Try again later ......

Conversion of SDK Internal Logs to Cache Files

// Default path: 1.4.11-1.4.12 /Library/Caches/FTLogs/FTLog xxxx-xx-xx--xx/xx/xx/xxx.log
//             >= 1.4.13 /Documents/FTLogs/FTLog.log

// >= 1.4.11
 [[FTLog sharedInstance] registerInnerLogCacheToLogsDirectory:nil fileNamePrefix:nil];

// >= 1.4.13
// Method one: Default path
 [[FTLog sharedInstance] registerInnerLogCacheToDefaultPath]
// Method two: Specified path
 NSString *filePath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES).firstObject 
stringByAppendingPathComponent:@"ExampleName.log"];
 [[FTLog sharedInstance] registerInnerLogCacheToLogsFilePath:filePath];

To ensure the integrity of internal logs, this configuration should be set before initializing the SDK

SDK Running Normally But No Data

  • Troubleshoot Datakit to ensure it is running normally

  • Confirm that the SDK upload address datakitUrl or datawayUrl is configured correctly and initialized properly. In debug mode, check the logs to determine upload issues.

  • Check if datakit is uploading data to the corresponding workspace and whether it is offline. This can be confirmed by logging into Guance and checking "Infrastructure".

Successful Data Collection Verification

Logger

Set the FTLoggerConfig option enableCustomLog = YES to enable the collection and reporting of custom logs.

When the SDK collects logs, you can see the SDK debug logs in the Xcode debugger console.

[FTLog][INFO] -[FTRecordModel initWithSource:op:tags:fields:tm:] [line 36] write data = {
    op = Logging;
    opdata =     {
        fields =         {
            message = "xxxxxCollected log contentXXXXX";
        };
        source = "df_rum_ios_log";
        tags =         {
             ...... 
        }
   }
}

Seeing op = Logging; indicates that the Logger function is enabled and data has been successfully collected.

RUM

When the SDK version is less than 1.4.14, Resource data and Action data (excluding launch action) are bound to View. Ensure that View data is being collected to collect data normally.

View collection: Set the FTRumConfig option enableTraceUserView = YES to enable automatic collection or manually collect -startViewWithName.

Check the SDK debug logs in the Xcode debugger console.

[FTLog][INFO] -[FTRecordModel initWithSource:op:tags:fields:tm:] [line 36] write data = {
    op = RUM;
    opdata =     {
        fields =       {
            .......
        };
        source = action;
        tags =         {
            ........
        }       
   }
}

Seeing op = RUM; indicates that the RUM function is enabled and data has been successfully collected.

Trace

If enableLinkRumData = YES is set, you can see it displayed in the RUM Resourse data. Check the SDK debug logs in the Xcode debugger console.

[FTLog][INFO] -[FTRecordModel initWithSource:op:tags:fields:tm:] [line 36] write data = {
    op = RUM;
    opdata =     {
        fields =         {
            duration = 5873084;
            "request_header" = "Accept:*/*\nx-datadog-parent-id:12914452039873665275\nx-datadog-trace-id:6849912365449426814\nx-datadog-origin:rum\nAccept-Language:en-US,en;q=0.9\nAccept-Encoding:gzip, deflate\nx-datadog-sampling-priority:2";
            ......
        };
        source = resource;
        tags =         {
            ......
            "span_id" = 12914452039873665275;
            "trace_id" = 6849912365449426814;
            ......
        };
    };

Find op = RUM; and source = resource; data where tags contain span_id and trace_id indicating that the Trace function is enabled.

Data Loss

Partial Data Loss

  1. If RUM loses some Session data or Log, Trace loses several pieces of data

First, exclude whether FTRUMConfig, FTLoggerConfig, FTTraceConfig has set sampleRate < 1.

  1. If RUM loses Resource events or Action events (excluding launch action)

Check if View auto-collection is enabled or if Open API manual collection is used. Resource events or Action events are bound to View. Ensure that View data is being collected to collect data normally.

  1. In SDK versions <= 1.4.14, if some data is lost and such debug logs are seen in the Xcode debugger console:
*********This data format is incorrect********
(null)*** 1717051153966272768
******************

Confirm that the NSDictionary type parameters passed to the SDK meet the following requirements:

  • All dictionary keys are NSStrings.

  • All objects are NSString, NSNumber, NSArray, NSDictionary, or NSNull.

  • NSNumber is not NaN or infinite.

It is recommended to use NSString for both keys and values.

  1. Investigate network and load issues with devices uploading data and datakit devices.

Error Data Loss Crash Type Data

  • Check if the Crash collection feature is enabled.

  • Ensure that the SDK initialization is completed before the crash occurs.

  • Check if other third-party components with crash capture functionality are used. If so, initialize FTMobileSDK after these components.

  • Check if in the Xcode debugging stage.

The SDK uses UNIX signals and Mach exceptions to capture crashes. Both of these methods are affected by the default Debug executable setting in Xcode. They intercept these exceptions before the SDK captures them. Therefore, if you want to capture crashes during debugging, you need to manually disable the Debug executable feature or test without Xcode connected. Note: After disabling Debug executable, breakpoint debugging will no longer work.

troubleshooting_debug_executable

Version Compatibility Issues

Missing Performance Metrics in RUM Resource Events

The SDK supports iOS 9 and above. To collect performance metrics in RUM Resource events, system-supported APIs for iOS 10 and above must be used. Thus, if the user's device runs a system below iOS 10, the collected Resource events will lack performance metric parts.

Carrier Attribute in RUM Error Data Shows --

In iOS 16.4 and above, CoreTelephony's CTCarrier is deprecated, and there is no replacement API. Using the deprecated method returns a static value --.

WebView

[xxViewController retain]: message sent to deallocated instance xxx

Affected Versions: SDK version <= 1.4.10

Cause: When using WebView, observers were added to the WebView. Before the observer was released, the observer was not removed from the WebView. Since the SDK internally strongly referenced the WebView, the WebView was not released. Subsequent KeyPath changes notified the observer, which had already been released, resulting in an EXC_BAD_ACCESS error.

Fix Suggestions:

  • Upgrade the SDK version

  • Or remove the observer before it is released.

   - (void)createWebView{
     [self.webView.scrollView addObserver:self forKeyPath:@"contentSize" options:NSKeyValueObservingOptionNew context:nil];
   }
   -(void)dealloc{
     [self.webView.scrollView removeObserver:self forKeyPath:@"contentSize"]
   }

Feedback

Is this page helpful? ×