To enable app hang monitoring:

1. Enable Crash Reporting.

2. Update the initialization snippet with the appHangThreshold parameter set to the minimal duration you want app hangs to be reported, in seconds. For example, use 0.25 to report hangs lasting at least 250 ms:

   RUM.enable(
       with: RUM.Configuration(
           applicationID: "<application id>",
           appHangThreshold: 0.25
       )
   )
   

   See Configure the app hang threshold for more guidance on setting this value.

   Make sure you follow the steps below to get deobfuscated stack traces, which transform cryptic memory addresses into readable function names and line numbers for effective debugging.

Choose the right threshold value based on your monitoring needs:

• For development and debugging:
  • Start with appHangThreshold: 0.25 seconds (250 ms) to catch most performance issues
  • Adjust incrementally (lower or higher) to find the right setup for your specific needs
• For production monitoring:
  • Set appHangThreshold between 2.0 and 3.0 seconds to filter out noisy hangs and focus on significant performance issues
  • This aligns with user experience expectations, where hangs under 2 seconds are less noticeable

Threshold limits

• Minimum: 0.1 seconds (100 ms) - however, setting the threshold to such small values may lead to an excessive reporting of hangs
• Recommended range: 0.25 to 3.0 seconds
• The SDK uses 2.5% tolerance to reduce CPU usage, which means some hangs that last close to the appHangThreshold may not be reported

Configuration example

RUM.enable(
    with: RUM.Configuration(
        applicationID: "<application id>",
        appHangThreshold: 2.0  // Report hangs lasting 2+ seconds
    )
)

To disable app hang monitoring, update the initialization snippet and set the appHangThreshold parameter to nil.

Every iOS application produces .dSYM files for each application module. These files minimize an application’s binary size and enable faster download speed. Each application version contains a set of .dSYM files.

Depending on your setup, you may need to download .dSYM files from App Store Connect or find them on your local machine.

By uploading your .dSYM files to Datadog, you gain access to the file path and line number of each frame in an error’s related stack trace.

After your application crashes and you restart the application, the iOS SDK uploads a crash report to Datadog.

Note: Re-uploading a .dSYM file with the same application version does not override the existing one.

export DATADOG_API_KEY="<API KEY>"

// if you have a zip file containing dSYM files
npx @datadog/datadog-ci dsyms upload appDsyms.zip

// if you have a folder containing dSYM files
npx @datadog/datadog-ci dsyms upload /path/to/appDsyms/

# For EU endpoint
export DATADOG_SITE="datadoghq.eu"
export DATADOG_API_KEY="<API KEY>"
npx @datadog/datadog-ci dsyms upload appDsyms.zip

# For custom intake URL
export DATADOG_DSYM_INTAKE_URL="https://your-custom-endpoint.com"
export DATADOG_API_KEY="<API KEY>"
npx @datadog/datadog-ci dsyms upload appDsyms.zip

name: Upload dSYM Files

jobs:
  build:
    runs-on: macos-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Generate/Download dSYM Files
        uses: ./release.sh

      - name: Upload dSYMs to Datadog
        uses: DataDog/upload-dsyms-github-action@v1
        with:
          api_key: ${{ secrets.DATADOG_API_KEY }}
          site: datadoghq.com
          dsym_paths: |
            path/to/dsyms/folder
            path/to/zip/dsyms.zip

To be compliant with the GDPR regulation, the iOS SDK requires the tracking consent value at initialization.

The trackingConsent setting can be one of the following values:

1. .pending: The iOS SDK starts collecting and batching the data but does not send it to Datadog. The iOS SDK waits for the new tracking consent value to determine what to do with the batched data.
2. .granted: The iOS SDK starts collecting the data and sends it to Datadog.
3. .notGranted: The iOS SDK does not collect any data, and doesn’t send logs, traces, or events to Datadog.

To change the tracking consent value after the iOS SDK is initialized, use the Datadog.set(trackingConsent:) API call. The iOS SDK changes its behavior according to the new value.

For example, if the current tracking consent is .pending:

• If you change the value to .granted, the iOS SDK sends all current and future data to Datadog.

• If you change the value to .notGranted, the iOS SDK wipes all current data and does not collect future data.

To control the data your application sends to Datadog, you can specify a sampling rate for sessions while initializing the iOS SDK. The rate is a percentage between 0 and 100. By default, sessionSamplingRate is set to 100 (keep all sessions).

For example, to only keep 50% of sessions, use:

let configuration = RUM.Configuration(
    applicationID: "<application id>",
    sessionSampleRate: 50
)

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<application id>"];
configuration.sessionSampleRate = 50;

The iOS SDK ensures data remains available when an end user’s device is offline. In cases of low-network areas, or when the device battery is too low, the device first stores all events in batches. It sends them as soon as the network is available and the battery is high enough to ensure the iOS SDK does not impact the end user’s experience. If the network is not available while your application is in the foreground, or if a data upload fails, the device keeps the batch until it can complete a successful upload.

This means that even if users open your application while offline, no data is lost.

Note: To ensure the iOS SDK does not use too much disk space, the device automatically discards the data on the disk if the data gets too old.

In the Apple ecosystem, the operating system employs a watchdog mechanism to monitor the health of applications, and terminates them if they become unresponsive or consume excessive resources like CPU and memory. These watchdog terminations are fatal and not recoverable (more details in the official Apple documentation).

By default, watchdog terminations reporting is disabled, but you can enable it by using the trackWatchdogTerminations initialization parameter.

When enabled, the app reports a watchdog termination and attaches to the previous user session on the next application launch, if all of the following conditions are true:

• The application was not upgraded in the meantime,

• And it did not call neither exit, nor abort,

• And it did not crash, either because of an exception, or because of a fatal app hang,

• And it was not force-quitted by the user,

• And the device did not reboot (which includes upgrades of the operating system).

Enable watchdog terminations reporting

To enable watchdog terminations reporting:

1. Enable Crash Reporting.

2. Update the initialization snippet with the trackWatchdogTerminations flag:

   RUM.enable(
       with: RUM.Configuration(
           applicationID: "<application id>",
           trackWatchdogTerminations: true
       )
   )
   

Disable watchdog terminations reporting

To disable watchdog terminations reporting, update the initialization snippet and set the trackWatchdogTerminations parameter to false.