Merge pull request #282 from flashcatcloud/docs/rum-native-metric-definitions

docs(rum): correct Native metric definitions, document iOS App Hang detection

Author: ysyneu

en/rum/analytics/native.mdx

@@ -14,7 +14,7 @@ The Insights dashboard includes 4 core analysis dimensions: **Overview**, **Perf
 
 The Native dashboard applies to Android, iOS, HarmonyOS, and Flutter apps, with the following platform-specific differences:
 
-- **Flutter**: A single Flutter app spans both Android and iOS, so the filter bar additionally pins the `os_name` filter to let you slice metrics by device OS. In the Overview and Error Analysis, the **ANR Rate** (from Android devices) and **App Hang Rate** (from iOS devices) cards are displayed side by side.
+- **Flutter**: A single Flutter app spans both Android and iOS, so the filter bar additionally pins the `os_name` filter to let you slice metrics by device OS. In the Overview and Error Analysis, the **ANR Rate** (from Android devices) and **Unresponsive Time Rate** (from App Hangs on iOS devices) cards are displayed side by side.
 - **HarmonyOS**: The SDK does not report performance or hang metrics yet, so hang-related cards are hidden and the "Performance" tab is not available.
 - **Electron**: Does not use the Native dashboard — Electron apps reuse the **Web Insights dashboard**, but UV is keyed on the anonymous ID (the Electron SDK does not report `usr_id`). See "Metrics Reference" below.
 </Note>
@@ -28,7 +28,7 @@ The Native dashboard applies to Android, iOS, HarmonyOS, and Flutter apps, with
 The Overview module focuses on core metrics across multiple dimensions for mobile apps:
 
 - **Traffic Metrics** - Monitor UV (Unique Visitors) and sessions to understand overall user activity trends
-- **Core Health Metrics** - Highlight three key mobile app metrics: crash count, crash-free rate, and app freeze rate for quick identification of stability issues
+- **Core Health Metrics** - Highlight three key mobile app metrics: crash count, crash-free rate, and unresponsive time rate for quick identification of stability issues
 - **User Access Trends** - Track UV and Session trends over time through time-series charts to understand user activity patterns
 - **User Distribution** - Analyze user sources by geographic location to understand regional user activity
 - **Session Analysis** - Track average session duration distribution trends to evaluate user engagement and usage depth
@@ -47,7 +47,7 @@ The Performance Analysis module focuses on full-chain monitoring of core experie
 The top section displays P75 percentile values for four key performance metrics:
 
 - **App Startup Time (P75)**: Monitor the P75 percentile of app startup duration to evaluate startup performance. Startup time directly impacts user first impressions and willingness to use the app.
-- **Frame Rate (P75)**: Display the P75 percentile of runtime frame rate to measure visual smoothness. Target is 60fps; higher values indicate smoother interactions.
+- **Frame Rate (P75)**: Display the P75 percentile of runtime frame rate to measure visual smoothness. Target is 60fps; higher values indicate smoother interactions. The SDKs normalize per-frame samples from high-refresh-rate screens (ProMotion, 120Hz Android devices) to a 60fps baseline and cap them at 60, so this metric reflects relative smoothness rather than the display's physical refresh rate.
 - **CPU Usage (P75)**: Track the P75 percentile of CPU utilization to identify compute-intensive operations. High CPU usage leads to device heating and increased battery drain.
 - **Memory Usage (P75)**: Monitor the P75 percentile of app memory usage to detect memory leaks or abnormal growth early.
 
@@ -70,7 +70,7 @@ Performance metrics by view name (Page/Activity/ViewController):
 
 App smoothness metrics by view name:
 
-- **Slow Frames**: Count of frames with rendering time exceeding threshold (typically 16.67ms, i.e., below 60fps), identifying jank issues. Slow frames cause users to perceive noticeable UI stuttering.
+- **Slow Frame Rate**: Milliseconds of rendering time spent on slow frames, per second of rendering (ms/s). A slow frame is one that exceeds the display's frame budget (about 16.67ms at 60fps) without reaching the frozen-frame threshold. The higher this value, the more stuttering users perceive. Mobile SDKs report only the rate, not a slow-frame count.
 - **Frozen Frames**: Count of completely frozen frames (typically exceeding 700ms), representing severe performance issues affecting user experience.
 - **Long Tasks**: Count of long-running tasks on the main thread (typically threshold of 100ms or longer), locating performance bottlenecks. Long tasks block user interactions and UI updates.
 - **Freeze Frequency**: Statistics of app freeze occurrence rate (per second), evaluating overall smoothness performance.
@@ -86,7 +86,7 @@ Memory usage details by view name:
 ## Error Analysis — Quick Error Identification and Diagnosis
 
 <Frame>
-  <img src="https://docs-cdn.flashcat.cloud/imges/png/b5868b87e52ddc7b82c61f685b2d0bd9.png" alt="Error analysis dashboard showing crash count, crash-free rate, ANR rate and app freeze rate" />
+  <img src="https://docs-cdn.flashcat.cloud/imges/png/b5868b87e52ddc7b82c61f685b2d0bd9.png" alt="Error analysis dashboard showing crash count, crash-free rate, ANR rate and unresponsive time rate" />
 </Frame>
 
 The Error Analysis module provides comprehensive error monitoring and diagnosis capabilities.
@@ -96,7 +96,7 @@ The Error Analysis module provides comprehensive error monitoring and diagnosis
 - **Crash Count**: Monitor total crash occurrences and trends to detect abnormal spikes early. Crashes force app termination and severely impact user experience.
 - **Crash-free Rate**: Track the percentage of crash-free sessions to evaluate overall app stability. Industry standard recommends maintaining crash-free rate above 99.5%.
 - **ANR Rate**: Statistics of Android Application Not Responding occurrence rate. ANR indicates the app's main thread has been blocked for more than 5 seconds, causing users to see the "App Not Responding" dialog.
-- **App Freeze Rate**: Monitor the percentage of sessions with freezes relative to total sessions, evaluating the impact scope of app smoothness issues. Freezes typically refer to UI freezing, response delays, or frame rate drops caused by long main thread blocking, affecting user interaction experience.
+- **Unresponsive Time Rate**: Seconds the main thread was unresponsive per hour of view time (seconds/hour), averaged by view time and counted only over views the SDK finished measuring. **This card is shown for iOS and Flutter apps only**; Android-only apps show the ANR Rate above instead. See "How to reduce unresponsive time rate?" below.
 
 #### Error Statistics
 
@@ -351,7 +351,7 @@ Common ANR causes:
 
 </Accordion>
 
-<Accordion title="How to reduce app freeze rate?">
+<Accordion title="How to reduce unresponsive time rate?">
 
 <Steps>
 <Step title="Locate Freeze Sources">
@@ -381,7 +381,11 @@ Common ANR causes:
 </Steps>
 
 <Note>
-Set reasonable freeze detection thresholds based on business characteristics and user expectations (recommended 200-500ms).
+The data source and threshold differ per platform:
+
+- **iOS**: Sourced from App Hangs, controlled by the SDK's `appHangThreshold`. This option **defaults to `nil`, meaning detection is off** — it must be set explicitly before any data is produced. A value of 0.25–0.5 seconds is recommended. See [iOS advanced configuration](/en/rum/sdk/ios/advanced-config).
+- **Android**: Sourced from main-thread freezes, counted only once a main-thread task reaches 5 seconds. The threshold is fixed and cannot be configured. Android-only apps do not show this metric — use the ANR Rate instead.
+- **Flutter**: One app spans both OSes, so ANR Rate and Unresponsive Time Rate appear side by side. Their thresholds differ, so do not compare them directly.
 </Note>
 
 </Accordion>
@@ -487,7 +491,7 @@ Flashduty RUM typically completes data collection and display within **1-3 minut
 
 | Metric | Collection Field | Good | Moderate | Poor |
 |--------|-----------------|------|----------|------|
-| App Startup Time | view_app_start_time | Within 2s | Within 4s | Over 4s |
+| App Startup Time | vital_duration (vital_type=app_launch, vital_app_launch_metric=ttid) | Within 2s | Within 4s | Over 4s |
 | Frame Rate | view_refresh_rate_average | 55 FPS or above | 50 FPS or above | Below 50 FPS |
 | CPU Usage | view_cpu_ticks_per_second | Below 40 ticks/s | Below 60 ticks/s | 60 ticks/s or above |
 | Memory Usage | view_memory_average | Below 100 MB | Below 200 MB | 200 MB or above |
@@ -497,19 +501,19 @@ Flashduty RUM typically completes data collection and display within **1-3 minut
 
 | Metric | Definition | Collection Field |
 |--------|-----------|-----------------|
-| Slow Frames | Frames with render time over 16ms | - |
-| Frozen Frames | Frames with render time over 700ms | - |
-| Long Tasks | Tasks with execution time over 100ms | long_task_duration |
-| Freeze Frequency | Average freezes per second | - |
+| Slow Frame Rate | Milliseconds of slow-frame time per second of rendering (ms/s) | view_slow_frames_rate |
+| Frozen Frames | Frames with render time over 700ms | view_frozen_frame_count |
+| Long Tasks | Tasks with execution time over 100ms | view_long_task_count |
+| Freeze Frequency | Frozen frames divided by view time, i.e. average freezes per second | - |
 
 ### Stability Metrics
 
 | Metric | Calculation | Description |
 |--------|------------|-------------|
 | Crash Count | Direct count | Total crashes caused by unhandled exceptions or signals |
-| Crash-free Rate | 1 minus crash session ratio | Recommended to maintain above 99% |
+| Crash-free Rate | Session-based: 1 minus (sessions with at least one crash / total sessions) | Recommended to maintain above 99%; a session that crashes several times still counts once. Android ANRs are not crashes and do not affect this metric |
 | ANR Rate | ANR sessions divided by total sessions | Triggered when UI thread blocked over 5 seconds (Android) |
-| App Freeze Rate | Freeze sessions divided by total sessions | Counted when main thread unresponsive over 250ms (iOS) |
+| Unresponsive Time Rate | Total unresponsive main-thread time divided by total view time, expressed as seconds/hour | iOS counts App Hangs and requires `appHangThreshold`; Android counts main-thread freezes that reach 5 seconds |
 
 ## Further Reading
 

en/rum/sdk/ios/advanced-config.mdx

@@ -247,6 +247,31 @@ RUM.enable(
 Sampled-out sessions will not collect any page views or related telemetry data.
 </Warning>
 
+## App Hang Detection
+
+An App Hang is a period during which the main thread is blocked and the UI cannot respond to user input. On iOS it is the only data source behind the **Unresponsive Time Rate** metric in the analytics dashboard.
+
+<Warning>
+`appHangThreshold` **defaults to `nil`, which means App Hang detection is off**. Unless you set it explicitly, your iOS app reports no App Hang data and the "Unresponsive Time Rate" card stays empty.
+</Warning>
+
+```swift
+RUM.enable(
+    with: RUM.Configuration(
+        applicationID: "<RUM_APPLICATION_ID>",
+        appHangThreshold: 0.25    // Record main-thread blocks longer than 250ms
+    )
+)
+```
+
+Notes:
+
+- The minimum allowed value is `0.1` seconds; lower values are raised to 0.1 automatically. For production, **0.25–0.5 seconds** is recommended, as a lower threshold produces a lot of noise.
+- The SDK detects hangs with a 2.5% tolerance, so hangs lasting very close to the threshold may not be reported.
+- Enable crash reporting as well, otherwise App Hang errors are reported without a stack trace.
+- An App Hang that never recovers, and ends with the system terminating the app, is recorded as a fatal error: it counts toward the crash count and lowers the crash-free rate. Non-fatal hangs are recorded as errors with `error.category = App Hang`.
+- Android has no equivalent option: its main-thread freeze threshold is fixed at 5 seconds.
+
 ## User Tracking Consent
 
 To comply with privacy regulations like GDPR and CCPA, you can set user tracking consent state:

en/rum/sdk/ios/data-collection.mdx

@@ -178,8 +178,8 @@ Different event types have specific attributes and metrics.
 | `view.is_slow_rendered` | Boolean | Whether view rendering is slow |
 | `view.crash.count` | Number | Number of crashes in this view |
 | `view.frozen_frame.count` | Number | Number of frozen frames in this view |
-| `view.refresh_rate_average` | Number | View average refresh rate |
-| `view.refresh_rate_min` | Number | View minimum refresh rate |
+| `view.refresh_rate_average` | Number | View average refresh rate. Samples from high-refresh-rate screens are normalized to a 60fps baseline and capped at 60. |
+| `view.refresh_rate_min` | Number | View minimum refresh rate. Normalized the same way. |
 | `view.memory_average` | Number | View average memory usage |
 | `view.memory_max` | Number | View maximum memory usage |
 | `view.cpu_ticks_count` | Number | View CPU tick count |