Troubleshooting¶

SDK Initialization Exception Verification¶

In the Debug environment, after you configure the TrueWatch SDK and run the application for the first time, please check your debugger console in Xcode. The SDK uses assertions to check the correctness of multiple configurations and will crash and output relevant warnings if configured incorrectly.

eg: When configuring the SDK, if the datakit metrics write address is not set, 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 enableSDKDebugLog = YES configuration item of FTMobileConfig in the Debug environment and disable it in the Release environment. The SDK's debug logs are prefixed with [FTLog] as an identifier, and you can filter using [FTLog].

Note: When the 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 Examples¶

Data Synchronization¶

// The following are normal synchronization logs
[FTLog][INFO] -[FTTrackDataManger flushWithEvents:type:] [line 143] ↵
                                                Start uploading events (Number of events in this upload: 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 was not printed. You can check the console for any error logs. If there are no error logs, the upload was 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 data synchronization related logs.

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 a path
 NSString *filePath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES).firstObject
stringByAppendingPathComponent:@"ExampleName.log"];
 [[FTLog sharedInstance] registerInnerLogCacheToLogsFilePath:filePath];

To ensure 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 upload issues
Check if datakit is uploading data to the corresponding workspace and if it is offline. This can be confirmed by logging into TrueWatch and viewing the "Infrastructure".

Verification of Successful Data Collection¶

Logger¶

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

When the SDK collects a log, you can see the SDK's debug log 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 launch action) are bound to the View. You need to ensure that the View is being collected for them to be collected normally.

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

Check the SDK's debug log 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, it can be seen in the RUM Resource data. Check the SDK's debug log 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; and source = resource;. If the tags contain span_id and trace_id, it indicates that the Trace function is enabled normally.

Data Loss¶

Partial Data Loss¶

If some data from a RUM Session, Log, or a few pieces of Trace data are lost

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

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

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

When the SDK version is <= 1.4.14, if some data is lost and you see such debug logs 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.

Troubleshoot network issues on the device uploading data and network/load issues on the device where datakit is installed.

Error Data Loss Crash Type Data¶

Check if Crash collection is enabled
Whether SDK initialization is completed before the Crash
Whether other third-party components with Crash capture functionality are used. If so, place the FTMobileSDK initialization after that component
Whether it is during 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 intercepts these exceptions before the SDK can capture 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 connected for debugging. Note: After disabling Debug executable, the breakpoint debugging function will become invalid.

Version Compatibility Issues¶

Missing Performance Metrics in RUM Resource Events¶

Affected versions: SDK version less than or equal to 1.3.10

The SDK supports iOS 9 and above. The performance metrics in RUM Resource events require APIs supported by iOS 10 and above for collection. 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 deprecated methods returns a static value --.

WebView¶

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

Affected versions: SDK version less than or equal to 1.4.10

Cause: When you use WebView, you added an observer to the WebView, and the WebView did not remove this observer before the observer was about to be released. Since the SDK internally holds a strong reference to the WebView, the WebView is not released. Later, when the observed KeyPath changes, it notifies the observer, but the observer has already 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"]
   }