Skip to content

SDK Diagnostics Log Upload

Jump to bottom
rsarika edited this page Apr 10, 2026 · 2 revisions

Background

When issues arise with the Webex iOS SDK, the most useful debugging artifacts are usually the SDK's diagnostic logs and, when applicable, audio dump files captured during a call or meeting.

Before uploadDiagnosticLogs(...), collecting those logs on iOS required one of these manual paths:

  • If the host app integrated getLogFileUrl(): the app had to create a local zip and then move that file to support through email, file sharing, or another app-specific workflow.
  • If the host app did not integrate a log-sharing flow: someone had to pull the app container from Xcode and browse to <App Sandbox>/Library/Caches/Logs.

The diagnostics upload API reduces that friction by letting the host app upload SDK diagnostics directly to the Webex backend and receive a feedback identifier for later lookup.

This branch also adds an iOS SDK-managed crash auto-upload flow. When enabled, the SDK installs iOS crash handlers, records supported SDK-attributed crash markers, and on the next launch uploads diagnostics through the same Omnius pipeline used by manual upload.

The existing local log export API remains available:

  • Webex.getLogFileUrl()

The direct upload API is:

  • Webex.uploadDiagnosticLogs(completionHandler:)

The crash auto-upload toggle is:

  • Webex.isCrashReportingEnabled

Manual Diagnostics Upload

This API uploads the current SDK diagnostics bundle to the Webex backend. On success, the completion handler returns a feedback identifier that can be used to retrieve the uploaded logs in Webex Control Hub.

webex.uploadDiagnosticLogs { result, feedbackId in
    switch result {
    case .noError:
        let uploadedFeedbackId = feedbackId
        // Use the feedback ID to locate the uploaded logs in Control Hub.
    default:
        print("Diagnostics upload failed: \(result.rawValue)")
    }
}

Crash Auto-Upload

Automatic crash upload is opt-in on iOS. Set isCrashReportingEnabled on the Webex instance before calling initialize(...).

let webex = Webex(authenticator: authenticator)
webex.isCrashReportingEnabled = true

webex.initialize { success in
    print("Initialized: \(success)")
}

Current source-backed behavior:

  • The feature is disabled by default.
  • The SDK auto-upload path is intended only for crashes attributed to SDK code.
  • The SDK suppresses crash auto-upload while a debugger is attached.
  • Pending crash upload is scheduled during initialize(...) when crash reporting is enabled and the SDK reaches a logged-in state.
  • Auto-upload reuses the same Omnius diagnostics transport as manual upload, but internally passes manualUpload: false.

What Gets Uploaded

The iOS diagnostics pipeline bundles SDK-generated diagnostics from the existing log area under:

  • Library/Caches/Logs

When crash auto-upload is enabled, the iOS crash manager also persists a crash report file at:

  • Library/Caches/Logs/extras/CrashReports/webexsdk-crash-report.txt

Implementation-backed details from this branch:

  • getLogFileUrl() zips Library/Caches/Logs into a temporary file.
  • Manual upload and crash auto-upload both flow through IOmniusService::uploadDiagnosticLogs(...).
  • Shared Omnius metadata differs by mode.
  • manualUpload == true uses source manual_feedback, issue type Diagnostics, and description SDK-generated diagnostics bundle.
  • manualUpload == false uses source crash_auto_upload, issue type CrashDiagnostics, and description SDK-generated crash diagnostics bundle.

Completion Handler Results

Result Description
noError Upload completed successfully. The feedback ID can be used to locate the logs in Webex Control Hub.
serviceUnavailable The native diagnostics service was unavailable, for example if the bridge could not obtain IOmniusService.
urlFailed Failed to obtain an upload URL from the backend.
uploadFailed Failed while uploading the diagnostics bundle.
metadataFailed Failed while posting or finalizing upload metadata.
sslError A TLS/SSL or certificate-related error occurred.
clientError A client-side request error occurred before the upload completed.
aborted The upload was aborted before completion.
zippingFailed Failed while creating the diagnostics zip bundle.
rateLimited The request was throttled by the backend.
internalError An unexpected internal error occurred.

Existing Local Log Export

Webex.getLogFileUrl() remains useful when the app wants to keep full control over how the diagnostics file is shared.

On iOS, that API:

  • reads logs from Library/Caches/Logs
  • creates a temporary zip at NSTemporaryDirectory()/webex-sdk-ios_temp_logs.zip
  • returns a URL pointing to that local file
if let logFileURL = webex.getLogFileUrl() {
    // Share or attach this file using your app's own workflow.
}

Testing Hooks

This branch also exposes public crash test helpers for validation environments:

  • triggerSDKCrashForTesting()
  • triggerNullDereferenceCrashForTesting()
  • triggerIllegalInstructionCrashForTesting()
  • triggerStackOverflowCrashForTesting()
  • triggerUncaughtExceptionForTesting()
  • triggerSIGFPECrashForTesting()
  • triggerSIGBUSCrashForTesting()

These APIs intentionally crash the process and should only be used in controlled test workflows.

Supported iOS Versions

The repository currently sets the iOS SDK deployment target to iOS 13.0.

Capability iOS support in this branch
uploadDiagnosticLogs(...) Supported
getLogFileUrl() Supported
isCrashReportingEnabled Supported
Next-launch SDK crash auto-upload path Supported
Shared Omnius crash auto-send transport Present

Rate Limiting

The iOS upload result surface includes a rateLimited outcome, so callers should expect backend throttling to be possible.

This branch does not document a public iOS-specific timing window for that throttling, so apps should treat rateLimited as a retry-later signal and avoid tight retry loops.

Important Limitations

  1. Crash auto-upload is disabled by default and must be explicitly enabled on each Webex instance.
  2. The iOS crash path is intended for SDK-attributed crashes, not arbitrary application crashes.
  3. Crash auto-upload is suppressed while a debugger is attached.
  4. Pending crash markers are cleared only after upload succeeds and returns a non-empty feedback ID.
  5. Completion handlers are not automatically marshaled onto the main queue by Webex.uploadDiagnosticLogs(...); dispatch UI updates to the main queue yourself.
  6. The temporary zip returned by getLogFileUrl() is a transient local file and should be treated as short-lived.

Related APIs

API Description
Webex.getLogFileUrl() Returns a local URL to a zip containing SDK log files. The app can share that file through its own channels.
Webex.uploadDiagnosticLogs(...) Uploads SDK diagnostics directly to the Webex backend and returns a feedback ID on success.
Webex.isCrashReportingEnabled Enables the iOS SDK crash auto-upload flow for SDK-attributed crashes.
Call.startRecordingAudioDump(...) Starts capturing audio dump data for an active call or meeting.
Call.stopRecordingAudioDump(...) Stops the current audio dump capture.

Related Documentation

  • products/sdk-ios/docs/Extracting SDK and WME logs
  • products/sdk-ios/docs/Troubleshooting Audio on Mobile SDK.md

Clone this wiki locally