Skip to content

Commit

Permalink
RUM mobile SDK docs restructure (#26629)
Browse files Browse the repository at this point in the history
* android

* Apply suggestions from code review

Co-authored-by: Pedro Lousada <[email protected]>

* add some ios and flutter folder

* flutter and kotlin

* kotlin roku unity rn

* add further reading partial

* remove rum in title and add missing files

* edit links

* update remaining links

* fix links for setup pages

* update partials

* partial for react native

* fixing some links

* remove multi code lang from kotlin

* more updated links

* remove sections

* fix link and add steps to android

* update sentence

* update header

* add error tracking tabs

* unity

* add image for ET

* ET updates for ios, expo, flutter, some kotlin

* rest of et updates

* update link

* add specific tabs and missing unity params

* take users directly to rn setup

* remove redundant link and add et android unity

* add et data collected to nav

* remove mobile vitals

* Apply suggestions from code review

Co-authored-by: Jen Gilbert <[email protected]>

* Apply suggestions from code review

Co-authored-by: Jen Gilbert <[email protected]>

* expo and codepush own sections

* old product lifecycle terms

* fix self-redirecting redirects

* fix links for expo error tracking

* add rn to codepush title

* no ampersand

* add same content to expo and codepush

* add to left nav

* add to left nav partial

* add separate entries for expo and codepush

* Revert "add to left nav partial"

This reverts commit d920695.

* Revert "add separate entries for expo and codepush"

This reverts commit 743bc98.

* Revert "add to left nav"

This reverts commit 6678e6f.

* Revert "add same content to expo and codepush"

This reverts commit 80dc298.

* Revert "no ampersand"

This reverts commit 14b2838.

* Revert "add rn to codepush title"

This reverts commit 866c104.

* Revert "fix links for expo error tracking"

This reverts commit 1d3f22b.

* revert

* remove rum and add direct tab links

* redirects so no 404s

* Apply suggestions from code review

Co-authored-by: StefonSimmons <[email protected]>

* remove unused partial

---------

Co-authored-by: Pedro Lousada <[email protected]>
Co-authored-by: Jen Gilbert <[email protected]>
Co-authored-by: StefonSimmons <[email protected]>
  • Loading branch information
4 people authored Dec 19, 2024
1 parent b758b98 commit b57688b
Show file tree
Hide file tree
Showing 108 changed files with 2,583 additions and 1,430 deletions.
14 changes: 7 additions & 7 deletions .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
Expand Up @@ -114,13 +114,13 @@ content/en/tracing/trace_collection/dd_libraries/ios.md @Datadog/rum-mob
content/en/tracing/**/*dotnet* @DataDog/tracing-dotnet @DataDog/documentation

# Mobile SDK
content/en/real_user_monitoring/mobile_and_tv_monitoring/setup/android/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/setup/flutter/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/setup/ios/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/setup/reactnative/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/setup/roku/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/setup/unity/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/setup/kotlin-multiplatform/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/android/setup/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/flutter/setup/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/ios/setup/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/react_native/setup/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/roku/setup/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/unity/setup/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/kotlin_multiplatform/setup/ @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/mobile_and_tv_monitoring/session_replay/mobile @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/error_tracking/android.md @Datadog/rum-mobile @DataDog/documentation
content/en/real_user_monitoring/error_tracking/expo.md @Datadog/rum-mobile @DataDog/documentation
Expand Down
350 changes: 325 additions & 25 deletions config/_default/menus/main.en.yaml

Large diffs are not rendered by default.

4 changes: 2 additions & 2 deletions content/en/data_security/real_user_monitoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,8 +146,8 @@ See [privacy options specific to Session Replay][19].
[6]: /real_user_monitoring/browser/tracking_user_actions/#declare-a-name-for-click-actions
[7]: /real_user_monitoring/guide/enrich-and-control-rum-data/?tab=event#event-and-context-structure
[8]: /real_user_monitoring/ios/advanced_configuration/?tab=swift#modify-or-drop-rum-events
[9]: /real_user_monitoring/mobile_and_tv_monitoring/advanced_configuration/android/?tab=kotlin#modify-or-drop-rum-events
[10]: /real_user_monitoring/mobile_and_tv_monitoring/advanced_configuration/flutter/#modify-or-drop-rum-events
[9]: /real_user_monitoring/mobile_and_tv_monitoring/android/advanced_configuration/?tab=kotlin#modify-or-drop-rum-events
[10]: /real_user_monitoring/mobile_and_tv_monitoring/flutter/advanced_configuration/#modify-or-drop-rum-events
[11]: /real_user_monitoring/reactnative/advanced_configuration/#modify-or-drop-rum-events
[12]: /real_user_monitoring/guide/proxy-rum-data/?tab=npm
[13]: /real_user_monitoring/browser/advanced_configuration/?tab=npm#user-session
Expand Down
2 changes: 1 addition & 1 deletion content/en/error_tracking/custom_grouping.md
Original file line number Diff line number Diff line change
Expand Up @@ -316,5 +316,5 @@ final configuration = DatadogConfiguration(
[1]: /tracing/
[2]: /logs/log_collection/
[3]: /real_user_monitoring/browser/
[4]: /real_user_monitoring/mobile_and_tv_monitoring/setup
[4]: /real_user_monitoring/mobile_and_tv_monitoring/#get-started
[5]: /error_tracking/default_grouping
2 changes: 1 addition & 1 deletion content/en/error_tracking/frontend/mobile/android.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@
title: Android Crash Reporting and Error Tracking
---

{{< include-markdown "real_user_monitoring/error_tracking/mobile/android" >}}
{{< include-markdown "real_user_monitoring/mobile_and_tv_monitoring/android/error_tracking" >}}
321 changes: 1 addition & 320 deletions content/en/error_tracking/frontend/mobile/ios.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,323 +2,4 @@
title: iOS Crash Reporting and Error Tracking
---

## Overview

Enable iOS Crash Reporting and Error Tracking to get comprehensive crash reports and error trends. With this feature, you can access:

- Aggregated iOS crash dashboards and attributes
- Symbolicated iOS crash reports
- Trend analysis with iOS error tracking

To symbolicate your stack traces, find and upload your `.dSYM` files to Datadog. Then, verify your configuration by running a test crash and restarting your application.

Your crash reports appear in [**Error Tracking**][1].

## Setup

If you have not set up the iOS SDK yet, follow the [in-app setup instructions][2] or see the [iOS setup documentation][3].

### Add crash reporting

To enable Crash Reporting, add the package according to your dependency manager and update your initialize snippet.

{{< tabs >}}
{{% tab "CocoaPods" %}}

You can use [CocoaPods][1] to install `dd-sdk-ios`:
```
pod 'DatadogCrashReporting'
```

[1]: https://cocoapods.org/

{{% /tab %}}
{{% tab "Swift Package Manager (SPM)" %}}

To integrate using Apple's Swift Package Manager, add the following as a dependency to your `Package.swift`:
```swift
.package(url: "https://github.com/Datadog/dd-sdk-ios.git", .upToNextMajor(from: "2.0.0"))
```

In your project, link the following libraries:
```
DatadogCrashReporting
```

{{% /tab %}}
{{% tab "Carthage" %}}

You can use [Carthage][1] to install `dd-sdk-ios`:
```
github "DataDog/dd-sdk-ios"
```

In Xcode, link the following frameworks:
```
DatadogCrashReporting.xcframework
CrashReporter.xcframework
```

[1]: https://github.com/Carthage/Carthage

{{% /tab %}}
{{< /tabs >}}

Update your initialization snippet to include Crash Reporting:

```swift
import DatadogCore
import DatadogCrashReporting

Datadog.initialize(
with: Datadog.Configuration(
clientToken: "<client token>",
env: "<environment>",
service: "<service name>"
),
trackingConsent: trackingConsent
)

CrashReporting.enable()
```

### Add app hang reporting

App hangs are an iOS-specific type of error that happens when the application is unresponsive for too long.

By default, app hangs reporting is **disabled**, but you can enable it and set your own threshold to monitor app hangs that last more than a specified duration by using the `appHangThreshold` initialization parameter. A customizable threshold allows you to find the right balance between fine-grained and noisy observability. See [Configure the app hang threshold][5] for more guidance on what to set this value to.

App hangs are reported through the iOS SDK (not through [Logs][4]).

When enabled, any main thread pause that is longer than the specified `appHangThreshold` is considered a _hang_ in [**Error Tracking**][1]. There are two types of hangs:

- **Fatal app hang**: How a hang gets reported if it never gets recovered and the app is terminated. Fatal app hangs are marked as a "Crash" in Error Tracking.

{{< img src="real_user_monitoring/error_tracking/ios-fatal-app-hang.png" alt="A fatal app hang in the Error side panel." style="width:60%;" >}}

- **Non-fatal app hang**: How a hang gets reported if the app recovers from a relatively short hang and continues running. Non-fatal app hangs do not have a "Crash" mark on them in Error Tracking.

{{< img src="real_user_monitoring/error_tracking/ios-non-fatal-app-hang.png" alt="A non-fatal app hang in the Error side panel." style="width:60%;" >}}

#### Enable app hang monitoring

To enable app hang monitoring:

1. [Enable Crash Reporting][19]

2. Update the initialization snippet with the `appHangThreshold` parameter:

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

3. Set the `appHangThreshold` parameter to the minimal duration you want app hangs to be reported. For example, enter `0.25` to report hangs lasting at least 250 ms. See [Configure the app hang threshold][5] for more guidance on what to set this value to.

Make sure you follow the steps below to get [deobfuscated stack traces][6].

#### Configure the app hang threshold

- Apple only considers hangs lasting more than 250 ms in their hang rate metrics in Xcode Organizer. Datadog recommends starting with a similar value for the `appHangThreshold` (in other words, set it to `0.25`) and then lowering it or increasing it incrementally to find the right setup.

- To filter out most of the noisy hangs, we recommend settling on an `appHangThreshold` between 2 and 3 seconds.

- The minimum value the `appHangThreshold` option can be set to is `0.1` seconds (100 ms). However, setting the threshold to such small values may lead to an excessive reporting of hangs.

- The SDK implements a secondary thread for monitoring app hangs. To reduce CPU utilization, it tracks hangs with a tolerance of 2.5%, which means some hangs that last close to the `appHangThreshold` may not be reported.


#### Disable app hang monitoring

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

### Add watchdog terminations reporting

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][12]).

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

When enabled, a watchdog termination is reported and attached to the previous user session on the next application launch, based on heuristics:

- 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][13],

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

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

{{< img src="real_user_monitoring/error_tracking/ios-watchdog-termination.png" alt="A watchdog termination in the Error Tracking side panel." style="width:60%;" >}}

#### Enable watchdog terminations reporting

To enable watchdog terminations reporting:

1. [Enable Crash Reporting][19]

2. Update the initialization snippet with the `trackWatchdogTerminations` flag:

```swift
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`.

## Get deobfuscated stack traces

Mapping files are used to deobfuscate stack traces, which helps in debugging errors. Using a unique build ID that gets generated, Datadog automatically matches the correct stack traces with the corresponding mapping files. This ensures that regardless of when the mapping file was uploaded (either during pre-production or production builds), the correct information is available for efficient QA processes when reviewing crashes and errors reported in Datadog.

For iOS applications, the matching of stack traces and symbol files relies on their `uuid` field.

### Symbolicate crash reports

Crash reports are collected in a raw format and mostly contain memory addresses. To map these addresses into legible symbol information, Datadog requires .`dSYM` files, which are generated in your application's build or distribution process.

### Find your .dSYM file

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.

| Bitcode Enabled | Description |
|---|---|
| Yes | `.dSYM` files are available after [App Store Connect][7] completes processing your application's build. |
| No | Xcode exports `.dSYM` files to `$DWARF_DSYM_FOLDER_PATH` at the end of your application's build. Ensure that the `DEBUG_INFORMATION_FORMAT` build setting is set to **DWARF with dSYM File**. By default, Xcode projects only set `DEBUG_INFORMATION_FORMAT` to **DWARF with dSYM File** for the Release project configuration. |

### Upload your .dSYM file

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

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

**Note**: Re-uploading a source map does not override the existing one if the version has not changed.

### Use Datadog CI to upload your .dSYM file

You can use the command line tool [@datadog/datadog-ci][8] to upload your `.dSYM` file:

```sh
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/
```

**Note**: To configure the tool using the EU endpoint, set the `DATADOG_SITE` environment variable to `datadoghq.eu`. To override the full URL for the intake endpoint, define the `DATADOG_DSYM_INTAKE_URL` environment variable.

Alternatively, if you use Fastlane or GitHub Actions in your workflows, you can leverage these integrations instead of `datadog-ci`:

### Use Fastlane plugin to upload your .dSYM file

The Fastlane plugin helps you upload `.dSYM` files to Datadog from your Fastlane configuration.

1. Add [`fastlane-plugin-datadog`][9] to your project.

```sh
fastlane add_plugin datadog
```

2. Configure Fastlane to upload your symbols.

```ruby
# download_dsyms action feeds dsym_paths automatically
lane :upload_dsym_with_download_dsyms do
download_dsyms
upload_symbols_to_datadog(api_key: "datadog-api-key")
end
```

For more information, see [`fastlane-plugin-datadog`][9].

### Use GitHub Actions to upload your .dSYM file

The [Datadog Upload dSYMs GitHub Action][10] allows you to upload your symbols in your GitHub Action jobs:

```yml
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
```

For more information, see [dSYMs commands][11].

## Limitations

{{< site-region region="us,us3,us5,eu,gov" >}}
dSYM files are limited to **500** MB.
{{< /site-region >}}
{{< site-region region="ap1" >}}
dSYM files are limited to **500** MB.
{{< /site-region >}}

## Test your implementation

To verify your iOS Crash Reporting and Error Tracking configuration, issue a crash in your application and confirm that the error appears in Datadog.

1. Run your application on an iOS simulator or a real device. Ensure that the debugger is not attached. Otherwise, Xcode captures the crash before the iOS SDK does.
2. Execute the code containing the crash:

```swift
func didTapButton() {
fatalError("Crash the app")
}
```

3. After the crash happens, restart your application and wait for the iOS SDK to upload the crash report in [**Error Tracking**][1].

**Note:** Error Tracking supports symbolication of system symbol files for iOS v14+ arm64 and arm64e architecture.


[1]: https://app.datadoghq.com/rum/error-tracking
[2]: https://app.datadoghq.com/rum/application/create
[3]: /real_user_monitoring/ios
[4]: /logs/log_collection/ios
[5]: /real_user_monitoring/error_tracking/mobile/ios/?tab=cocoapods#configure-the-app-hang-threshold
[6]: /real_user_monitoring/error_tracking/mobile/ios/?tab=cocoapods#get-deobfuscated-stack-traces
[7]: https://appstoreconnect.apple.com/
[8]: https://www.npmjs.com/package/@datadog/datadog-ci
[9]: https://github.com/DataDog/datadog-fastlane-plugin
[10]: https://github.com/marketplace/actions/datadog-upload-dsyms
[11]: https://github.com/DataDog/datadog-ci/blob/master/src/commands/dsyms/README.md
[12]: https://developer.apple.com/documentation/xcode/addressing-watchdog-terminations
[13]: /real_user_monitoring/error_tracking/mobile/ios/?tab=cocoapods#add-app-hang-reporting
[14]: /real_user_monitoring/mobile_and_tv_monitoring/mobile_vitals?tab=ios#telemetry
[15]: https://developer.apple.com/documentation/xcode/analyzing-responsiveness-issues-in-your-shipping-app#View-your-apps-hang-rate
[16]: https://developer.apple.com/documentation/metrickit/mxhangdiagnostic
[17]: /real_user_monitoring/explorer/search/#facets
[18]: /dashboards/widgets/timeseries
[19]: /real_user_monitoring/error_tracking/mobile/ios/?tab=cocoapods#add-crash-reporting
{{< include-markdown "real_user_monitoring/mobile_and_tv_monitoring/ios/error_tracking" >}}
2 changes: 1 addition & 1 deletion content/en/logs/log_collection/flutter.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ final datadogLogger = DatadogSdk.instance.logs?.createLogger(


[1]: https://pub.dev/packages/datadog_flutter_plugin
[2]: /real_user_monitoring/mobile_and_tv_monitoring/setup/flutter
[2]: /real_user_monitoring/mobile_and_tv_monitoring/flutter/setup
[3]: https://pub.dev/documentation/datadog_flutter_plugin/latest/datadog_flutter_plugin/DatadogLoggerConfiguration-class.html
[4]: /getting_started/tagging/
[5]: https://api.flutter.dev/flutter/services/StandardMessageCodec-class.html
Expand Down
2 changes: 1 addition & 1 deletion content/en/logs/log_collection/roku.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,6 @@ To ensure the SDK doesn't use too much disk space, the data on the disk is autom
[3]: /account_management/api-app-keys/#api-keys
[4]: /logs/processing/attributes_naming_convention/
[5]: /tagging/
[6]: /real_user_monitoring/mobile_and_tv_monitoring/setup/roku/?tab=us
[6]: /real_user_monitoring/mobile_and_tv_monitoring/roku/setup/?tab=us
[7]: https://github.com/DataDog/dd-sdk-roku/releases
[8]: https://developer.roku.com/fr-fr/docs/developer-program/getting-started/architecture/file-system.md#cachefs
2 changes: 1 addition & 1 deletion content/en/real_user_monitoring/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -211,5 +211,5 @@ Access triggered logs, errors, and performance information when troubleshooting
[13]: /real_user_monitoring/session_replay/browser/privacy_options/
[14]: /real_user_monitoring/session_replay/browser/developer_tools/
[15]: /real_user_monitoring/browser/setup/
[16]: /real_user_monitoring/mobile_and_tv_monitoring/setup/
[16]: /real_user_monitoring/mobile_and_tv_monitoring/
[17]: https://app.datadoghq.com/rum/optimization/inspect
Loading

0 comments on commit b57688b

Please sign in to comment.