latency troubleshooting

Author: laujan

articles/ai-services/document-intelligence/concept/troubleshoot-latency.md

@@ -1,26 +1,28 @@
 ---
 title: Troubleshoot latency issues with Document Intelligence API
 titleSuffix: Azure AI services
-description: Learn troubleshooting tips, remedial solutions, and best practices to address Document Intelligence latency issues.
+description: Learn troubleshooting tips, remedial solutions, and best practices for addressing Document Intelligence latency issues.
 author: laujan
 manager: nitinme
 ms.service: azure-ai-document-intelligence
 ms.topic: troubleshooting
-ms.date: 02/03/2025
+ms.date: 02/05/2025
 ms.author: lajanuar
 ---
 
 # Troubleshooting latency issues in Azure AI Document Intelligence
 
-This article presents troubleshooting tips, remedial solutions, and best practices to address Document Intelligence latency issues. Your applications can encounter latency with using the Document Intelligence service. Latency refers to the duration an API server takes to handle and process an incoming request before delivering the response to the client. The time required to analyze a document varies based on its size (such as the number of pages) and the content on each page. Document Intelligence operates as a multitenant service, ensuring that latency for similar documents is generally comparable, though not always identical. Variability in latency and performance is an inherent characteristic of any microservice-based, stateless, asynchronous service, especially when processing images and large documents on a large scale. Despite continuous efforts to increase hardware capacity and enhance scalability, some latency issues can still arise during runtime.
+This article presents troubleshooting tips, remedial solutions, and best practices to address Document Intelligence latency issues. Latency refers to the duration an API server takes to handle and process an incoming request before delivering the response to the client. The time required to analyze a document varies based on its size (such as the number of pages) and the content on each page. Document Intelligence operates as a multitenant service, ensuring that latency for similar documents is comparable, though not always identical. Variability in latency and performance is an inherent characteristic of any microservice-based, stateless, asynchronous service, especially when processing images and large documents on a large scale. Despite continuous efforts to increase hardware capacity and enhance scalability, some latency issues can still arise during runtime.
 
 > [!NOTE]
-> Azure AI services doesn't offer a Service Level Agreement (SLA) for latency.
-> The asynchronous nature of the API allows you to retrieve results for up to 24 hours after the operation is sent to our backend with the request Id returned by the POST operation. If you are unable to retrieve the result within your normal polling sequence, store the request Id and attempt at a different time before retrying. Please refer to our service page for more guidance.
+> Azure AI services don't provide a Service Level Agreement (SLA) for latency.
+> The Document Intelligence API offers asynchronous functionality, allowing you to access results up to 24 hours after sending your request to our backend. Use the request ID provided by the POST operation to retrieve these results. If you encounter issues during your standard polling sequence, save the request ID and try again later before considering a retry. For further assistance, refer to our service page.
+
+To evaluate latency, you should first establish baseline metrics for your specific scenario. These metrics give you the expected end-to-end and server latency within the context of your application environment. Once you have these baseline metrics, it becomes easier to distinguish between abnormal and normal conditions.
 
 ## Check Azure region status
 
-If you're experiencing latency issues, the first to check [Azure status](https://azure.status.microsoft/status) to determine whether there is an ongoing outage or issue impacting your services.
+If you're experiencing latency issues, the first step is to check [Azure status](https://azure.status.microsoft/status) for any current outages or issues that might impact your services.
 
 * All active events are listed under the `Current Impact` tab.
 
@@ -30,11 +32,11 @@ If you're experiencing latency issues, the first to check [Azure status](https:/
 
 ## Check file size
 
-The size of the files you may be sending through the request API. The service parallelizes processing, larger files can lead to longer processing time. Please normalize your measurement as latency per page. Consider raising the issue if you see sustained periods (more than an hour) with latency per page consistently being above 15s.
+Monitor the size of files you send via the request API. Processing larger files in parallel can result in increased processing times. Normalize your metric by measuring latency per page. If you observe sustained periods (exceeding one hour) where latency per page consistently surpasses 15 seconds, consider addressing the issue.
 
 ## Check Azure Blob storage latency
 
-Latency in Azure Storage operations is affected by the size of the request. Larger operations take more time to complete due to the increased volume of data transferred over the network and processed by Azure Storage.
+The size of a request affects latency in Azure Storage operations. Larger operations take more time to complete due to the increased volume of data transferred over the network and processed by Azure Storage.
 
 Azure Storage provides two latency metrics for block blobs in the Azure portal:
 
@@ -56,9 +58,60 @@ For more information, *see* [Latency in Blob storage](/azure/storage/blobs/stora
 
 ## Check monitoring metrics for your resource
 
-You can monitor performance metrics and set up alerts for your Document Intelligence resource in the Azure portal. To view latency metrics, navigate to your Document Intelligence resource in the Azure portal:
+Azure portal monitors offer insights into your applications to enhance their performance and availability. There are several tools that you can use to monitor your app's performance in the Azure portal:
+
+1.  On the **Overview** page, select **Monitoring**, select the time period, and review the **Request latency** metrics on page.
+
+    :::image type="content" source="../media/latency/azure-portal-monitoring.png" alt-text="Screenshot of Azure usage monitoring metrics in the Azure portal.":::
+
+1. On the left navigation window, select **Metrics** from the **Monitoring** drop-down menu.
+
+   * In the main window, select ➕**Add metric**.
+
+   * Keep the **Scope** and **Metric Namespace** fields unchanged. Add the **Latency** parameter to the **Metric** field and adjust the **Aggregation** field as needed.
+
+      :::image type="content" source="../media/latency/azure-portal-monitoring-metrics.png" alt-text="Screenshot of add your own metrics setting in the Azure portal.":::
+
+## Set a latency alert in the Azure portal
+
+Alerts assist you in identifying and resolving issues by providing proactive notifications when Azure Monitor data suggests a potential issue. An alert rule keeps an eye on your data and notifies you when set criteria are met on your specified resource. You can set up an alert in the Azure portal as follows:
+
+1. On the left navigation window, select **Alerts** from the **Monitoring** drop-down menu.
+
+1. Select the **Create alert rule** button.
+
+1. In the new window that opens, select **Latency** from the **Select a signal** drop-down menu.
+
+   :::image type="content" source="../media/latency/azure-portal-create-alert.png" alt-text="Screenshot of the create an alert rule page in the Azure portal":::
+
+1. Configure the alert by completing the fields on the page.
+
+1. After you complete the configuration, select **Review ➕ create**
+
+
+ ### Contact us
+
+If you're unable to resolve long latency issue, [email us](mailto:[email protected]) with the following information:
+
+* Model Name
+
+* Version
+
+* Subscription ID
+
+* Resource ID
+
+* Timestamp and issue description
+
+* Request IDs of the concerning operations (if possible)
+
+* Logs
+
+* Sample files
+
+* JSON file (output/analyze results)
 
-* On the **Overview** page, select **Monitoring**, select the time period, and review the **Request latency** metrics on page.
+* Training set (if it's a training issue related to custom neural models)
 
-   :::image type="content" source="../media/latency/azure-portal-monitoring.png" alt-text="Screenshot of Azure usage monitoring metrics in the Azure portal.":::
 
+For more assistance, you can also or use the feedback widget at the bottom of any Microsoft Learn page.