Merge pull request #230459 from JustPies/jprefresh-3-10

Freshness Pass User Story: 2036619 Monitor and debug with insights in Azure Cosmos DB

Author: v-regandowner

articles/cosmos-db/use-metrics.md

@@ -1,19 +1,21 @@
 ---
 title: Monitor and debug with insights in Azure Cosmos DB
-description: Use metrics in Azure Cosmos DB to debug common issues and monitor the database.
+description: Learn how to use metrics and insights in Azure Cosmos DB to debug common issues and monitor the database.
 ms.author: esarroyo
 author: StefArroyo 
 ms.reviewer: mjbrown
 ms.service: cosmos-db
 ms.subservice: nosql
 ms.topic: how-to
-ms.date: 11/08/2021
+ms.date: 03/13/2023
 ms.custom: devx-track-csharp, ignite-2022
 ---
+
 # Monitor and debug with insights in Azure Cosmos DB
+
 [!INCLUDE[NoSQL, MongoDB, Cassandra, Gremlin, Table](includes/appliesto-nosql-mongodb-cassandra-gremlin-table.md)]
 
-Azure Cosmos DB provides insights for throughput, storage, consistency, availability, and latency. The Azure portal provides an aggregated view of these metrics. You can also view Azure Cosmos DB metrics from Azure Monitor API. The dimension values for the metrics such as container name are case-insensitive. So you need to use case-insensitive comparison when doing string comparisons on these dimension values. To learn about how to view metrics from Azure monitor, see the [Get metrics from Azure Monitor](./monitor.md) article.
+Azure Cosmos DB provides insights for throughput, storage, consistency, availability, and latency. The Azure portal provides an aggregated view of these metrics. You can also view Azure Cosmos DB metrics from Azure Monitor API. The dimension values for the metrics such as container name are case-insensitive. Therefore, you need to use case-insensitive comparison when doing string comparisons on these dimension values. To learn how to view metrics from Azure monitor, see [Monitor Azure Cosmos DB](./monitor.md).
 
 This article walks through common use cases and how Azure Cosmos DB insights can be used to analyze and debug these issues. By default, the metric insights are collected every five minutes and are kept for seven days.
 
@@ -23,57 +25,57 @@ This article walks through common use cases and how Azure Cosmos DB insights can
 
 1. You can view your account metrics either from the **Metrics** pane or the **Insights** pane.
 
-   * **Metrics:** This pane provides numerical metrics that are collected at regular intervals and describe some aspect of a system at a particular time. For example, you can view and monitor the [server side latency metric](monitor-server-side-latency.md), [normalized request unit usage metric](monitor-normalized-request-units.md) etc.
+   * **Metrics:** This pane provides numerical metrics that are collected at regular intervals and describes some aspect of a system at a particular time. For example, you can view and monitor the [server side latency metric](monitor-server-side-latency.md), [normalized request unit usage metric](monitor-normalized-request-units.md), etc.
 
-   * **Insights:** This pane provides a customized monitoring experience for Azure Cosmos DB. They use the same metrics and logs that are collected in Azure Monitor and shows an aggregated view for your account.
+   * **Insights:** This pane provides a customized monitoring experience for Azure Cosmos DB. Insights use the same metrics and logs that are collected in Azure Monitor and show an aggregated view for your account.
 
-1. Open the **Insights** pane. By default, the Insights pane shows the throughput, requests, storage, availability, latency, system, and account management metrics for every container in your account. You can select the **Time Range**, **Database**, and **Container** for which you want to view insights. The **Overview** tab shows RU/s usage, data usage, index usage, throttled requests, and normalized RU/s consumption for the selected database and container.
+1. Open the **Insights** pane. By default, the Insights pane shows the throughput, requests, storage, availability, latency, system, and management operations metrics for every container in your account. You can select the **Time Range**, **Database**, and **Container** for which you want to view insights. The **Overview** tab shows RU/s usage, data usage, index usage, throttled requests, and normalized RU/s consumption for the selected database and container.
 
-   :::image type="content" source="./media/use-metrics/performance-metrics.png" alt-text="Azure Cosmos DB performance metrics in Azure portal" lightbox="./media/use-metrics/performance-metrics.png" :::
+   :::image type="content" source="./media/use-metrics/performance-metrics.png" alt-text="Screenshot of Azure Cosmos DB performance metrics in the Azure portal." lightbox="./media/use-metrics/performance-metrics.png" :::
 
 1. The following metrics are available from the **Insights** pane:
 
-   * **Throughput** - This tab shows the total number of request units consumed or failed (429 response code) because the throughput or storage capacity provisioned for the container has exceeded.
+   * **Throughput**. This tab shows the total number of request units consumed or failed (429 response code) because the throughput or storage capacity provisioned for the container has exceeded.
 
-   * **Requests** - This tab shows the total number of requests processed  by status code, by operation type, and the count of failed requests (429 response code). Requests fail when the throughput or storage capacity provisioned for the container exceeds.
+   * **Requests**. This tab shows the total number of requests processed by status code, by operation type, and the count of failed requests (429 response code). Requests fail when the throughput or storage capacity provisioned for the container exceeds.
 
-   * **Storage** - This tab shows the size of data and index usage over the selected time period.
+   * **Storage**. This tab shows the size of data and index usage over the selected time period.
 
-   * **Availability** - This tab shows the percentage of successful requests over the total requests per hour. The success rate is defined by the Azure Cosmos DB SLAs.
+   * **Availability**. This tab shows the percentage of successful requests over the total requests per hour. The Azure Cosmos DB SLAs defines the success rate.
 
-   * **Latency** - This tab shows the read and write latency observed by Azure Cosmos DB in the region where your account is operating. You can visualize latency across regions for a geo-replicated account. You can also view server-side latency by different operations. This metric doesn't represent the end-to-end request latency.
+   * **Latency**. This tab shows the read and write latency observed by Azure Cosmos DB in the region where your account is operating. You can visualize latency across regions for a geo-replicated account. You can also view server-side latency by different operations. This metric doesn't represent the end-to-end request latency.
 
-   * **System** - This tab shows how many metadata requests are served by the primary partition. It also helps to identify the throttled requests.
+   * **System**. This tab shows how many metadata requests that the primary partition serves. It also helps to identify the throttled requests.
 
-   * **Account management** - This tab shows the metrics for account management activities such as account creation, deletion, key updates, network and replication settings.
+   * **Management Operations**. This tab shows the metrics for account management activities such as account creation, deletion, key updates, network and replication settings.
 
 The following sections explain common scenarios where you can use Azure Cosmos DB metrics.
 
 ## Understand how many requests are succeeding or causing errors
 
-To get started, head to the [Azure portal](https://portal.azure.com) and navigate to the **Insights** blade. From this blade, open the **Requests** tab, it shows a chart with the total requests segmented by the status code and operation type. For more information about HTTP status codes, see [HTTP status codes for Azure Cosmos DB](/rest/api/cosmos-db/http-status-codes-for-cosmosdb).
+To get started, head to the [Azure portal](https://portal.azure.com) and navigate to the **Insights** pane. From this pane, open the **Requests** tab. The Requests tab shows a chart with the total requests segmented by the status code and operation type. For more information about HTTP status codes, see [HTTP status codes for Azure Cosmos DB](/rest/api/cosmos-db/http-status-codes-for-cosmosdb).
 
-The most common error status code is 429 (rate limiting/throttling). This error means that requests to Azure Cosmos DB are more than the provisioned throughput. The most common solution to this problem is to [scale up the RUs](./set-throughput.md) for the given collection.
+The most common error status code is 429 (rate limiting/throttling). This error means that requests to Azure Cosmos DB are more than the provisioned throughput. The most common solution to this problem is to scale up the RUs for the given collection. For more information, see [Introduction to provisioned throughput in Azure Cosmos DB](./set-throughput.md)
 
-:::image type="content" source="media/use-metrics/request-count.png" alt-text="Number of requests per minute" lightbox= "media/use-metrics/request-count.png":::
+:::image type="content" source="media/use-metrics/request-count.png" alt-text="Screenshot showing total requests by status code, throttled requests, and total requests by operation type." lightbox="media/use-metrics/request-count.png":::
 
 ## Determine the throughput consumption by a partition key range
 
-Having a good cardinality of your partition keys is essential for any scalable application. To determine the throughput distribution of any partitioned container broken down by partition key range IDs, navigate to the **Insights** pane. Open the **Throughput** tab, the normalized RU/s consumption across different partition key ranges is shown in the chart.
+Having a good cardinality of your partition keys is essential for any scalable application. To determine the throughput distribution of any partitioned container broken down by partition key range IDs, navigate to the **Insights** pane. Open the **Throughput** tab. The normalized RU/s consumption across different partition key ranges is shown in the chart.
 
-:::image type="content" source="media/use-metrics/throughput-consumption-partition-key-range.png" alt-text="Normalized throughput consumption by partition key range IDs" lightbox="media/use-metrics/throughput-consumption-partition-key-range.png":::
+:::image type="content" source="media/use-metrics/throughput-consumption-partition-key-range.png" alt-text="Screenshot of the Throughput tab, showing the RU/s consumption." lightbox="media/use-metrics/throughput-consumption-partition-key-range.png":::
 
-With the help of this chart, you can identify if there is a hot partition. An uneven throughput distribution may cause *hot* partitions, which can result in throttled requests and may require repartitioning. After identifying which partition key is causing the skew in distribution, you may have to repartition your container with a more distributed partition key. For more information about partitioning in Azure Cosmos DB, see [Partition and scale in Azure Cosmos DB](./partitioning-overview.md).
+With the help of this chart, you can identify if there's a hot partition. An uneven throughput distribution might cause *hot* partitions, which can result in throttled requests and might require repartitioning. After identifying which partition key is causing the skew in distribution, you might have to repartition your container with a more distributed partition key. For more information about partitioning in Azure Cosmos DB, see [Partitioning and horizontal scaling in Azure Cosmos DB](./partitioning-overview.md).
 
 ## Determine the data and index usage
 
-It's important to determine the storage distribution of any partitioned container by data usage, index usage, and document usage. You can minimize the index usage, maximize the data usage and optimize your queries. To get this data, navigate to the **Insights** pane and open the **Storage** tab:
+It's important to determine the storage distribution of any partitioned container by data usage, index usage, and document usage. You can minimize the index usage, maximize the data usage, and optimize your queries. To get this data, navigate to the **Insights** pane and open the **Storage** tab.
 
-:::image type="content" source="media/use-metrics/data-index-consumption.png" alt-text="Data, index, and document consumption" lightbox="media/use-metrics/data-index-consumption.png" :::
+:::image type="content" source="media/use-metrics/data-index-consumption.png" alt-text="Screenshot of the Insights pane, highlighting the Storage tab." lightbox="media/use-metrics/data-index-consumption.png" :::
 
 ## Compare data size against index size
 
-In Azure Cosmos DB, the total consumed storage is the combination of both the Data size and Index size. Typically, the index size is a fraction of the data size. To learn more, see the [Index size](index-policy.md#index-size) article. In the Metrics blade in the [Azure portal](https://portal.azure.com), the Storage tab showcases the breakdown of storage consumption based on data and index.
+In Azure Cosmos DB, the total consumed storage is the combination of both the data size and index size. Typically, the index size is a fraction of the data size. To learn more, see the [Index size](index-policy.md#index-size) article. In the Metrics pane in the [Azure portal](https://portal.azure.com), the Storage tab showcases the breakdown of storage consumption based on data and index.
 
 ```csharp
 // Measure the document size usage (which includes the index size)  
@@ -83,7 +85,7 @@ ResourceResponse<DocumentCollection> collectionInfo = await client.ReadDocumentC
 
 If you would like to conserve index space, you can adjust the [indexing policy](index-policy.md).
 
-## Debug why queries are running slow
+## Debug slow queries
 
 In the API for NoSQL SDKs, Azure Cosmos DB provides query execution statistics.
 
@@ -104,12 +106,11 @@ FeedResponse<dynamic> result = await query.ExecuteNextAsync();
 IReadOnlyDictionary<string, QueryMetrics> metrics = result.QueryMetrics;
 ```
 
-*QueryMetrics* provides details on how long each component of the query took to execute. The most common root cause for long running queries is scans, meaning the query was unable to leverage the indexes. This problem can be resolved with a better filter condition.
+*QueryMetrics* provides details on how long each component of the query took to execute. The most common root cause for long running queries is scans, meaning the query was unable to apply the indexes. This problem can be resolved with a better filter condition.
 
 ## Next steps
 
-You've now learned how to monitor and debug issues using the metrics provided in the Azure portal. You may want to learn more about improving database performance by reading the following articles:
+You might want to learn more about improving database performance by reading the following articles:
 
-* To learn about how to view metrics from Azure monitor, see the [Get metrics from Azure Monitor](./monitor.md) article. 
-* [Performance and scale testing with Azure Cosmos DB](performance-testing.md)
-* [Performance tips for Azure Cosmos DB](performance-tips.md)
+* [Measure Azure Cosmos DB for NoSQL performance with a benchmarking framework](performance-testing.md)
+* [Performance tips for Azure Cosmos DB and .NET SDK v2](performance-tips.md)