Merge pull request #208580 from ealsur/users/ealsur/netpolish

Cosmos DB: Polishing NET troubleshooting docs

Author: 19BMG00

articles/cosmos-db/sql/troubleshoot-dot-net-sdk-slow-request.md

@@ -4,7 +4,7 @@ description: Learn how to diagnose and fix slow requests when you use Azure Cosm
 author: ealsur
 ms.service: cosmos-db
 ms.subservice: cosmosdb-sql
-ms.date: 07/08/2022
+ms.date: 08/19/2022
 ms.author: maquaran
 ms.topic: troubleshooting
 ms.reviewer: mjbrown
@@ -27,8 +27,12 @@ When you design your application, [follow the .NET SDK best practices](performan
 Consider the following when developing your application:
 
 * The application should be in the same region as your Azure Cosmos DB account.
-* The SDK has several caches that have to be initialized, which might slow down the first few requests. 
-* The connectivity mode should be direct and TCP.
+* Your [ApplicationRegion](/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.applicationregion), [ApplicationPreferredRegions](/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.applicationpreferredregions), or [PreferredLocations](/dotnet/api/microsoft.azure.documents.client.connectionpolicy.preferredlocations) for V2 SDK configuration is should reflect your regional preference and point to the region your application is deployed on.
+* There might be a bottleneck on the Network interface because of high traffic. If the application is running on Azure Virtual Machines, there are possible workarounds:
+  * Consider using a [Virtual Machine with Accelerated Networking enabled](../../virtual-network/create-vm-accelerated-networking-powershell.md).
+  * Enable [Accelerated Networking on an existing Virtual Machine](../../virtual-network/create-vm-accelerated-networking-powershell.md#enable-accelerated-networking-on-existing-vms).
+  * Consider using a [higher end Virtual Machine](../../virtual-machines/sizes.md).
+* Prefer [direct connectivity mode](sql-sdk-connection-modes.md).
 * Avoid high CPU. Make sure to look at the maximum CPU and not the average, which is the default for most logging systems. Anything above roughly 40 percent can increase the latency.
 
 ## Metadata operations

articles/cosmos-db/sql/troubleshoot-dot-net-sdk.md

@@ -3,7 +3,7 @@ title: Diagnose and troubleshoot issues when using Azure Cosmos DB .NET SDK
 description: Use features like client-side logging and other third-party tools to identify, diagnose, and troubleshoot Azure Cosmos DB issues when using .NET SDK.
 author: seesharprun
 ms.service: cosmos-db
-ms.date: 03/05/2021
+ms.date: 08/19/2022
 ms.author: sidandrews
 ms.reviewer: mjbrown
 ms.subservice: cosmosdb-sql
@@ -63,9 +63,8 @@ If your app is deployed on [Azure Virtual Machines without a public IP address](
 * Assign a [public IP to your Azure VM](../../load-balancer/troubleshoot-outbound-connection.md#configure-an-individual-public-ip-on-vm).
 
 ### <a name="high-network-latency"></a>High network latency
-High network latency can be identified by using the [diagnostics string](/dotnet/api/microsoft.azure.documents.client.resourceresponsebase.requestdiagnosticsstring) in the V2 SDK or [diagnostics](/dotnet/api/microsoft.azure.cosmos.responsemessage.diagnostics#Microsoft_Azure_Cosmos_ResponseMessage_Diagnostics) in V3 SDK.
 
-If no [timeouts](troubleshoot-dot-net-sdk-request-timeout.md) are present and the diagnostics show single requests where the high latency is evident.
+High network latency can be identified by using the diagnostics.
 
 # [V3 SDK](#tab/diagnostics-v3)
 
@@ -76,20 +75,6 @@ ItemResponse<MyItem> response = await container.CreateItemAsync<MyItem>(item);
 Console.WriteLine(response.Diagnostics.ToString());
 ```
 
-Network interactions in the diagnostics will be for example:
-
-```json
-{
-    "name": "Microsoft.Azure.Documents.ServerStoreModel Transport Request",
-    "id": "0e026cca-15d3-4cf6-bb07-48be02e1e82e",
-    "component": "Transport",
-    "start time": "12: 58: 20: 032",
-    "duration in milliseconds": 1638.5957
-}
-```
-
-Where the `duration in milliseconds` would show the latency.
-
 # [V2 SDK](#tab/diagnostics-v2)
 
 The diagnostics are available when the client is configured in [direct mode](sql-sdk-connection-modes.md), through the `RequestDiagnosticsString` property:
@@ -98,33 +83,13 @@ The diagnostics are available when the client is configured in [direct mode](sql
 ResourceResponse<Document> response = await client.ReadDocumentAsync(documentLink, new RequestOptions() { PartitionKey = new PartitionKey(partitionKey) });
 Console.WriteLine(response.RequestDiagnosticsString);
 ```
-
-And the latency would be on the difference between `ResponseTime` and `RequestStartTime`:
-
-```bash
-RequestStartTime: 2020-03-09T22:44:49.5373624Z, RequestEndTime: 2020-03-09T22:44:49.9279906Z,  Number of regions attempted:1
-ResponseTime: 2020-03-09T22:44:49.9279906Z, StoreResult: StorePhysicalAddress: rntbd://..., ...
-```
 --- 
 
-This latency can have multiple causes:
-
-* Your application is not running in the same region as your Azure Cosmos DB account.
-* Your [PreferredLocations](/dotnet/api/microsoft.azure.documents.client.connectionpolicy.preferredlocations) or [ApplicationRegion](/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.applicationregion) configuration is incorrect and is trying to connect to a different region to where your application is currently running on.
-* There might be a bottleneck on the Network interface because of high traffic. If the application is running on Azure Virtual Machines, there are possible workarounds:
-    * Consider using a [Virtual Machine with Accelerated Networking enabled](../../virtual-network/create-vm-accelerated-networking-powershell.md).
-    * Enable [Accelerated Networking on an existing Virtual Machine](../../virtual-network/create-vm-accelerated-networking-powershell.md#enable-accelerated-networking-on-existing-vms).
-    * Consider using a [higher end Virtual Machine](../../virtual-machines/sizes.md).
+Please see our [latency troubleshooting guide](troubleshoot-dot-net-sdk-slow-request.md) once you have obtained diagnostics for the affected operations.
 
 ### Common query issues
 
-The [query metrics](sql-api-query-metrics.md) will help determine where the query is spending most of the time. From the query metrics, you can see how much of it is being spent on the back-end vs the client. Learn more about [troubleshooting query performance](troubleshoot-query-performance.md).
-
-* If the back-end query returns quickly, and spends a large time on the client check the load on the machine. It's likely that there are not enough resource and the SDK is waiting for resources to be available to handle the response.
-* If the back-end query is slow, try [optimizing the query](troubleshoot-query-performance.md) and looking at the current [indexing policy](../index-overview.md)
-
-    > [!NOTE]
-    > For improved performance, we recommend Windows 64-bit host processing. The SQL SDK includes a native ServiceInterop.dll to parse and optimize queries locally. ServiceInterop.dll is supported only on the Windows x64 platform. For Linux and other unsupported platforms where ServiceInterop.dll isn't available, an additional network call will be made to the gateway to get the optimized query.
+The [query metrics](sql-api-query-metrics.md) will help determine where the query is spending most of the time. From the query metrics, you can see how much of it is being spent on the back-end vs the client. Learn more on the [query performance guide](performance-tips-query-sdk.md?pivots=programming-language-csharp).
 
 If you encounter the following error: `Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies:` and are using Windows, you should upgrade to the latest Windows version.
 

articles/cosmos-db/sql/troubleshoot-service-unavailable.md

@@ -4,7 +4,7 @@ description: Learn how to diagnose and fix Azure Cosmos DB service unavailable e
 author: rothja
 ms.service: cosmos-db
 ms.subservice: cosmosdb-sql
-ms.date: 08/06/2020
+ms.date: 08/19/2022
 ms.author: jroth
 ms.topic: troubleshooting
 ms.reviewer: mjbrown
@@ -13,7 +13,15 @@ ms.reviewer: mjbrown
 # Diagnose and troubleshoot Azure Cosmos DB service unavailable exceptions
 [!INCLUDE[appliesto-sql-api](../includes/appliesto-sql-api.md)]
 
-The SDK wasn't able to connect to Azure Cosmos DB.
+The SDK wasn't able to connect to Azure Cosmos DB. This scenario can be transient or permanent depending on the network conditions.
+
+It is important to make sure the application design is following our [guide for designing resilient applications with Azure Cosmos DB SDKs](conceptual-resilient-sdk-applications.md) to make sure it correctly reacts to different network conditions. Your application should have retries in place for service unavailable errors.
+
+When evaluating the case for service unavailable errors:
+
+* What is the impact measured in volume of operations affected compared to the operations succeeding? Is it within the service SLAs?
+* Is the P99 latency affected?
+* Are the failures affecting all your application instances or only a subset? When the issue is reduced to a subset of instances, it's commonly a problem related to those instances.
 
 ## Troubleshooting steps
 The following list contains known causes and solutions for service unavailable exceptions.
@@ -22,12 +30,7 @@ The following list contains known causes and solutions for service unavailable e
 Verify that all the [required ports](sql-sdk-connection-modes.md#service-port-ranges) are enabled.
 
 ### Client-side transient connectivity issues
-Service unavailable exceptions can surface when there are transient connectivity problems that are causing timeouts. Typically, the stack trace related to this scenario will contain a `TransportException` error. For example:
-
-```C#
-TransportException: A client transport error occurred: The request timed out while waiting for a server response. 
-(Time: xxx, activity ID: xxx, error code: ReceiveTimeout [0x0010], base error: HRESULT 0x80131500
-```
+Service unavailable exceptions can surface when there are transient connectivity problems that are causing timeouts and can be safely retried following the [design recommendations](conceptual-resilient-sdk-applications.md#timeouts-and-connectivity-related-failures-http-408503).
 
 Follow the [request timeout troubleshooting steps](troubleshoot-dot-net-sdk-request-timeout.md#troubleshooting-steps) to resolve it.
 
@@ -37,4 +40,6 @@ Check the [Azure status](https://azure.status.microsoft/status) to see if there'
 
 ## Next steps
 * [Diagnose and troubleshoot](troubleshoot-dot-net-sdk.md) issues when you use the Azure Cosmos DB .NET SDK.
-* Learn about performance guidelines for [.NET v3](performance-tips-dotnet-sdk-v3-sql.md) and [.NET v2](performance-tips.md).
+* [Diagnose and troubleshoot](troubleshoot-java-sdk-v4-sql.md) issues when you use the Azure Cosmos DB Java SDK.
+* Learn about performance guidelines for [.NET](performance-tips-dotnet-sdk-v3-sql.md).
+* Learn about performance guidelines for [Java](performance-tips-java-sdk-v4-sql.md).