Troubleshooting¶

SDK Initialization Exception Validation¶

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

eg: When configuring the SDK, if the datakit metrics write address is not set, the program will crash, and a warning ⚠️ will be output 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 enableSDKDebugLog = YES configuration item of FTMobileConfig in the Debug environment and disable it in the Release environment. The debug logs of the SDK are prefixed with [FTLog], and you can filter using [FTLog].

Note: When scheme sets OS_ACTIVITY_MODE=disable, the SDK debug logs cannot be output normally. 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¶

// The following are normal synchronization logs
[FTLog][INFO] -[FTTrackDataManger flushWithEvents:type:] [line 143] ↵
                                                Start uploading events (Number of events uploaded 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

Before version 1.3.10, Upload Response statusCode : 200 would not be printed. You can check the console for error logs. If there are no error logs, the upload is successful.

Error logs: Network failure: ...... or Server exception, try again later ......

After version 1.5.16, you can search for [NETWORK] in the logs to view all logs related to data synchronization.

Convert 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 1: Default path
 [[FTLog sharedInstance] registerInnerLogCacheToDefaultPath]
//  Method 2: Specify path
 NSString *filePath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES).firstObject 
stringByAppendingPathComponent:@"ExampleName.log"];
 [[FTLog sharedInstance] registerInnerLogCacheToLogsFilePath:filePath];

For the integrity of internal logs, this configuration needs to be set before SDK initialization

SDK Runs Normally but No Data¶

Check if Datakit is running normally
Confirm that the SDK upload address datakitUrl or datawayUrl is configured correctly and initialized correctly. In debug mode, check the logs to determine the upload issue
Check if datakit is uploading data to the corresponding workspace and if it is offline. This can be confirmed by logging into Guance and checking the "Infrastructure".

Data Collection Success Verification¶

Logger¶

Set the enableCustomLog = YES configuration item of FTLoggerConfig to enable custom log collection and reporting.

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

[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 normally and data is successfully collected.

RUM¶

When the SDK version is less than 1.4.14, Resource data and Action data (except for launch action) are bound to View. You need to ensure that View is collected to collect them normally.

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

Check the SDK debug logs in the debugger console in Xcode.

[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 normally and data is successfully collected.

Trace¶

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

[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 the data with op = RUM; source = resource;, and if span_id and trace_id are included in tags, it indicates that the Trace function is enabled normally.

Data Loss¶

Partial Data Loss¶

If some Session data or Log, Trace data in RUM is lost

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

If Resource events or Action events (except for launch action) in RUM are lost

Check if View automatic collection is enabled or if Open API manual collection is used. Resource events or Action events are bound to View. You need to ensure that View is collected to collect them normally.

When the SDK version <= 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
******************

Please confirm whether the NSDictionary type parameters passed to the SDK meet the following requirements:

All dictionary keys are NSString
All objects are NSString, NSNumber, NSArray, NSDictionary, or NSNull
NSNumber is not NaN or infinity

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

Check the network of the device uploading data and the network and load of the device where datakit is installed.

Error Data Loss Crash Type Data¶

Check if Crash collection is enabled
Whether SDK initialization is completed before Crash
Whether other third-party components with Crash capture function are used. If so, place FTMobileSDK initialization after these components
Whether it is in the Xcode debugging phase

The SDK uses UNIX signals and Mach exceptions to capture crashes. Both capture methods are affected by Debug executable, which is enabled by default in Xcode. It will intercept these exceptions before the SDK captures them. Therefore, if you want to capture crashes normally during the debugging phase, you need to manually disable the Debug executable function or test without Xcode connection debugging. Note: After disabling Debug executable, the breakpoint debugging function will be invalid.

Version Compatibility Issues¶

Performance Metrics Missing in RUM Resource Events¶

Affected versions: SDK versions less than or equal to 1.3.10

The SDK supports iOS 9 and above. The performance metrics in RUM Resource events need to be collected using APIs supported by iOS 10 and above. Therefore, if the user's device uses a system below iOS 10, the collected Resource events will lack the performance metrics part.

The `carrier` Attribute in RUM Error Data Shows `--`¶

In iOS 16.4 and above, CTCarrier in CoreTelephony is deprecated, and there is no replacement API. Using the deprecated method will return a static value --.

WebView¶

[xxViewController retain]: message sent to deallocated instance xxx¶

Affected versions: SDK versions less than or equal to 1.4.10

Reason: When using WebView, if an observer is added to the WebView, and the observer is not removed before it is about to be released. Since the SDK internally strongly references the WebView, the WebView is not released. When the observed KeyPath changes later, it will notify the observer, but the observer has been released, resulting in an EXC_BAD_ACCESS error.

Fix Suggestions:

Upgrade the SDK version
Or remove the observer before it is about to be released.

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