appium app profiling doc

docs/appium-app-performance.md

@@ -39,130 +39,146 @@ import {YOUR_LAMBDATEST_USERNAME, YOUR_LAMBDATEST_ACCESS_KEY} from "@site/src/co
       })
     }}
 ></script>
-When it comes to building an application, tracking its performance is crucial. You can follow the performance of your applications with LambdaTest's Real Device cloud platform on metrics like CPU consumption, network usage and many more. Go through the page below to understand each metric that LambdaTest provides you with.
 
-## Metrics
+App performance is critical factor for user satisfaction and adoption. Identifying and resolving bottlenecks early is essential for delivering a high-quality experience but it requires constant monitoring and optimization across various device metrics. LambdaTest’s App Profiling feature helps you to detect and optimize performance issues before release by providing real-time insights into key metrics like CPU usage, memory consumption, and network activity on real devices.
 
-### 1. CPU Consumption
+You can enable performance tracking in your existing automation tests with the following capability:
 
-The CPU is responsible for carrying out all the operations in a mobile device. As it is a shared resource, high usage by a single app can affect other running services. 
+```javascript
+"appProfiling" : true;
+```
 
-Moreover, high CPU usage can also cause high battery usage. You can work around this by identifying and addressing areas of high CPU usage. This will increase the efficiency of your app and reduce its overall resource utilisation. Reducing the CPU consumption of your application improves performance and provides the user with a smoother experience. 
+> This feature is available for Appium tests on **iOS and Android (version 9+)**. For full functionality, ensure the `resignApp` capability is set to `true`.
 
-LambdaTest provides you with two metrics in a time-series format representing the following:
+<img loading="lazy" src={require('../assets/images/appium-app/app-profiling.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-1. **System CPU Usage (%)**: The total percentage of CPU being used by the entire system
+## Basic Summary
+Here is a description of each metric from the App Profiling summary:
 
-2. **App CPU Usage (%)**: The share of "System CPU usage" being used by the AUT.
+- **Cold Startup Time :** Time taken by the app to launch from a complete shutdown or a non-running state. A lower cold startup time improves user experience, as it reduces wait time when the app is opened for the first time.
+- **Hot Startup Time :** Time taken by the app to resume from a background state. A fast hot startup ensures that users can quickly switch between apps without delays.
+- **Maximum CPU Utilisation :** It indicates the peak percentage of CPU consumed by the app during its execution. High CPU utilization can affect other processes and contribute to battery drain, so it's important to keep it optimized.
+- **Average CPU :** Average CPU utilization gives a more balanced view of the app’s typical CPU usage during a session. This value helps assess the app’s efficiency in resource usage over time.
+- **Maximum Memory Usage :** It refers to the highest amount of RAM consumed by the app during the session. Monitoring this metric helps developers ensure that their app doesn't consume excessive memory, which can lead to slower performance or crashes on low-memory devices.
+- **Average Memory Usage :** Average memory usage shows the typical amount of memory used by the app. This value is useful for identifying memory leaks and optimizing the overall resource consumption of the application.
+- **Maximum Disk Usage :** Highest amount of storage consumed by the app on the device. Keeping disk usage minimal helps improve app performance and ensures better storage management for end users.
+- **Average Disk Usage :** It reflects the typical amount of storage space used by the app over time. This metric is important for identifying opportunities to reduce the app’s footprint on the device's storage.
+- **Average Frame Rate :** The frame rate measures the smoothness of the app’s graphical rendering. A higher frame rate (measured in frames per second or fps) indicates smoother animations and a better visual experience. A rate close to 60 fps or higher is typically desired for smooth app performance.
+- **Network Download/Upload :** This metric tracks the amount of data downloaded and uploaded by the app during the session. Monitoring network usage helps developers optimize how the app handles data transmission to ensure it uses bandwidth efficiently.
+- **Application Not Responding :** ANR events occur when the app becomes unresponsive and prompts the user to wait or close the app. A value of zero indicates the app has not faced any ANR issues, which is crucial for maintaining a stable and responsive app. You can also ANR Dumps, and Data logs.
+- **App Crashes :** This metric tracks the number of times the app has crashed during the session. Zero crashes indicate that the app is stable, ensuring a reliable user experience.
 
-<img loading="lazy" src={require('../assets/images/appium-app/cpu.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
+## Key Performance Metrics
 
-***
+### 1. CPU Consumption
+The CPU handles all operations within a mobile device. High CPU usage impacts overall system performance and drains the battery faster. By monitoring CPU consumption, you can pinpoint which features are resource-heavy and optimize them for better performance. LambdaTest provides two CPU metrics in a time-series format:
 
-### 2. Memory Consumption
+- **System CPU Usage (%):** Total CPU usage across the system.
+- **App CPU Usage (%):** CPU usage specific to your app.
 
-Memory or RAM is one of the most critical resources in a mobile device. Identifying areas where your application is consuming more than expected memory is essential. 
+Using these insights, you can minimize CPU-intensive operations, delivering a smoother user experience and enhancing device efficiency.
 
-You can also identify areas of your application that may be causing memory leaks. Memory leaks can cause your application to consume more and more memory over time, leading to decreased performance and eventually causing the application to crash. 
+<img loading="lazy" src={require('../assets/images/appium-app/cpu.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-LambdaTest provides you with three metrics in a time-series format representing the following:
+### 2. Memory Consumption
+RAM is a critical resource for mobile apps. Excessive memory consumption can lead to memory leaks, degraded performance, and application crashes.
 
-1. Memory Consumed by the system (in MB) throughout the session
-2. Memory Consumed by your application (in MB) throughout the session
-3. Memory Available for use (in MB) throughout the session
+LambdaTest offers three memory metrics:
+- **System Memory Usage (MB):** Overall memory consumption during the session.
+- **App Memory Usage (MB):** Memory consumed by your application.
+- **Available Memory (MB):** Remaining memory available for use.
 
+By tracking these, you can optimize memory utilization and prevent crashes caused by memory leaks.
 <img loading="lazy" src={require('../assets/images/appium-app/memory.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-***
+### 3. Disk Usage
+The Disk Usage metric provides insights into how much disk space is being utilized by both the system and the application during a session. Monitoring disk usage is crucial for optimizing storage consumption and ensuring efficient app performance, especially on devices with limited storage capacity.
 
-### 3. Battery 
+- **System Disk (MB):** Indicates the total amount of disk space used by the entire system, including the operating system and other background processes, displayed in megabytes (MB).
+- **App Disk (MB):** Shows the disk space specifically consumed by your application (App Under Test) during the session, helping you track how much space your app is utilizing and whether it might cause storage-related issues.
 
-A high-performing app could also drain the mobile device's battery quickly, affecting the overall usage of the device and its performance. 
+<img loading="lazy" src={require('../assets/images/appium-app/disk.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-You can monitor the battery drained while using your app and subsequently optimize the features that may contribute to a lot of battery drain, improving the battery life of devices running your app.
+### 4. Rendering (Frame Rate)
+Smooth rendering directly affects how responsive your app feels to users. Rendering performance is a typical performance issue that any app faces. It is measured at different stages in the app’s lifecycle to ensure that users do not have a bad experience with the app. 
 
-<img loading="lazy" src={require('../assets/images/appium-app/battery.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
+LambdaTest measures your app's Frames Per Second (FPS) across its lifecycle, which helps you identify performance bottlenecks in rendering and improve user experience.
 
-***
+- **Frames Per Second (FPS):** Real-time measurement of rendering performance throughout the session.
 
-### 4. Temperature
-
-You can identify elements that cause the battery to overheat by monitoring the battery temperatures while using your app. This might help you decide which features to optimise first to save energy and prolong the battery life of the devices running your app. You won't have to worry about your smartphone overheating or encountering performance issues due to a heated battery, improving the user experience.
-
-<img loading="lazy" src={require('../assets/images/appium-app/temperature.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
-
-***
-
-### 5. Rendering (Frame Rate)
+<img loading="lazy" src={require('../assets/images/appium-app/rendering.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-Rendering performance is a typical performance issue that any app faces. Rendering is measured at different stages in the app’s lifecycle to ensure that users do not have a bad experience with the app. 
+### 5. Network Usage
+Understanding how your app utilizes network resources is essential for optimizing data transfer and ensuring efficient performance.
 
-LambdaTest provides the frames rate or FPS (frames per second) observed throughout the session.
+LambdaTest tracks:
+- **Download Size (MB):** Amount of data downloaded during the session.
+- **Upload Size (MB):** Amount of data uploaded during the session.
 
-<img loading="lazy" src={require('../assets/images/appium-app/rendering.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
+This helps you to monitor:
 
-***
+- **Data Efficiency:** Optimize data usage to enhance performance and reduce costs.
+- **Performance Optimization:** Identify and mitigate high network usage areas that may affect app responsiveness.
 
-### 6. Network Usage
-
-Tracking the amount of data your app sends and receives can help you understand how it uses the network. By looking at this data over time, you can see when and how your app sends data and use it to make code changes to improve its performance. 
+<img loading="lazy" src={require('../assets/images/appium-app/network.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-You can use your application to monitor how much data it operates on an actual device, which can help you identify and optimise areas of high network usage. 
+### 6. Battery Consumption
+Apps that consume excessive battery negatively affect user experience. With LambdaTest, you can monitor how your app impacts battery drain, identify features that are energy hogs, and optimize them. This will help extend battery life for devices running your app.
 
-LambdaTest provides the following information to capture network usage better:
-1. Network download size throughout the session in time-series
-2. Network upload size throughout the session in time-series
+- **Battery Drain Rate:** Amount of battery consumed while using the app.
 
-<img loading="lazy" src={require('../assets/images/appium-app/network.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
+<img loading="lazy" src={require('../assets/images/appium-app/battery.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-***
+### 7. Temperature Monitoring
+High device temperature can degrade performance and harm the user experience. LambdaTest lets you monitor battery temperature during app usage, helping you optimize features causing excessive heat generation and reducing the risk of device overheating.
 
-### 7. ANR (Application Not Responding)
+- **Temperature:** Temperature of the device battery during app usage.
 
-Sometimes, your application stops responding, and you receive a pop-up to wait or close the app. Knowing what part of the application's life cycle results in an ANR and in which condition is critical. Such instances can ruin the user experience, especially when inputting any information. 
+<img loading="lazy" src={require('../assets/images/appium-app/temperature.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-LambdaTest provides information on the number of times your app faced ANR and a dump of logs to find more details quickly. However, this feature is supported only for Android devices for now. 
+### 8. ANR (Application Not Responding)
 
-***
+Sometimes, your application stops responding, and you receive a pop-up to wait or close the app. Application freezes and crashes are frustrating for users. LambdaTest provides detailed logs on ANR events, that helps you diagnose the root causes and eliminate them.
 
-### 8. Application Start-up Time
+> Currently, ANR monitoring is available for **Android devices** only.
 
-A faster startup time means a better user experience. By identifying and addressing bottlenecks in the startup process, you can improve the overall performance of your app. 
+Metrics Provided:
 
-This can result in a more responsive and smoother user experience. Currently, you can view the cold start-up time and hot start-up time separately, with cold start-up time being supported for Android devices.
+- **ANR Count:** Number of times the app encountered ANR during the session.
+- **Log Dumps:** Detailed logs for each ANR event to aid in troubleshooting.
 
-***
+### 9. Application Start-up Time
+Application start-up time significantly impacts the first impression and overall user experience. Slow startup times create a poor first impression. LambdaTest tracks both cold and hot startup times for Android devices, giving you the data needed to reduce delays and deliver a faster app launch.
 
-## Starting a Performance Session
+## Fetch your App Profiling details via API
+LambdaTest provides an API that allows you to programmatically access detailed app profiling metrics captured during your test sessions. By integrating this API into your CI/CD pipelines or automation frameworks, you can fetch real-time data such as CPU usage, memory consumption, disk usage, and network activity for deeper analysis. This enables continuous monitoring and performance optimization without manual intervention.
 
-### Track the Metrics via App Automation
+To retrieve profiling details, simply make a request to the LambdaTest API using your **authentication token (username and access key)** and the relevant **session ID**. The response will include comprehensive metrics in JSON format, allowing easy integration with other tools or reporting systems for further insights.
 
-You can track the performance metrics for your application inside an app automation test. The data will be captured at the test level and shown on the test details page. Just add the following capability inside your test, and set it to `true`.
+<div className="lambdatest__codeblock">
+  <CodeBlock className="language-bash">
+    {`https://${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}@mobile-api.lambdatest.com/mobile-automation/api/v1/sessions/SESSION_ID/log/appmetrics`}
+  </CodeBlock>
+</div>
 
-```javascript
-"appProfiling" : true;
-```
+**Step 1:** Run your app automation test on the Real Device Cloud.
 
-:::tip
-The `appProfiling` flag is supported for Appium tests on iOS and Android devices. However, it is only supported on devices with an **Android version >=9** and tests where the `resignApp` capability is not set to `false`. 
-:::
+**Step 2:** Get your **SESSION_ID** from the **Meta Data** section. 
+<img loading="lazy" src={require('../assets/images/appium-app/meta-data.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-:::note
-You can also also use this API to enable the app profiling feature in your tests:
+**Step 3:** Replace the `YOUR_SESSION_ID` parameter in the given API with your actual session id.
 
-  <div className="lambdatest__codeblock">
-    <CodeBlock className="language-bash">
-      {`https://${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}@mobile-api.lambdatest.com/mobile-automation/api/v1/sessions/`}
-    </CodeBlock>
-  </div>
+<div className="lambdatest__codeblock">
+  <CodeBlock className="language-bash">
+    {`https://${ YOUR_LAMBDATEST_USERNAME()}:${ YOUR_LAMBDATEST_ACCESS_KEY()}@mobile-api.lambdatest.com/mobile-automation/api/v1/sessions/YOUR_SESSION_ID/log/appmetrics`}
+  </CodeBlock>
+</div>
 
-:::
+**Step 4:** Now go to any API testing platform, and pass the above URL (GET Method) to fetch the relevant results.
 
-A sample output of this test will look like: 
+<img loading="lazy" src={require('../assets/images/appium-app/app-profiling-api-result.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-<img loading="lazy" src={require('../assets/images/appium-app/app-profiling.png').default} alt="cmd" width="768" height="373" className="doc_img"/>
 
-***
 
 > Got any questions?<br/>
 > Please reach out at our <span className="doc\_\_lt" onClick={() => window.openLTChatWidget()}>**24x7 Chat Support**</span> or you could also mail us at [[email protected]](https://support.lambdatest.com/).