Merge pull request #186760 from deborahc/dech-cosmos-partitioning-docs

How to create an alert for 20 GB logical partition limits

Author: Court72

articles/cosmos-db/TOC.yml

@@ -1587,7 +1587,11 @@
             - name: Audit control plane logs
               href: audit-control-plane-logs.md
         - name: Configure alerts
-          href: create-alerts.md
+          items:
+            - name: Create alert on Metrics
+              href: create-alerts.md
+            - name: Create alert on logical partition key size
+              href: how-to-alert-on-logical-partition-key-storage-size.md
         - name: Monitoring data reference
           href: monitor-cosmos-db-reference.md
         - name: Application logging with Logic Apps

articles/cosmos-db/concepts-limits.md

@@ -35,7 +35,7 @@ You can provision throughput at a container-level or a database-level in terms o
 | Minimum RU/s required per 1 GB | 10 RU/s<br>**Note:** this minimum can be lowered if your account is eligible to our ["high storage / low throughput" program](set-throughput.md#high-storage-low-throughput-program) |
 
 > [!NOTE]
-> To learn about best practices for managing workloads that have partition keys requiring higher limits for storage or throughput, see [Create a synthetic partition key](synthetic-partition-keys.md). If your workload has already reached the logical partition limit of 20GB in production, it is recommended to re-architect your application with a different partition key as a long-term solution. To help give time for this, you can request a temporary increase in the logical partition key limit for your existing application. [File an Azure support ticket](create-support-request-quota-increase.md) and select quota type **Temporary increase in container's logical partition key size**. Note this is intended as a temporary mitigation and not recommendeded as a long-term solution, as SLA guarantees are not honored when the limit is increased. To remove the configuration, file a support ticket and select quota type **Restore container’s logical partition key size to default (20 GB)**. This can be done after you have either deleted data to fit the 20 GB logical partition limit or have re-architected your application with a different partition key.
+> To learn about best practices for managing workloads that have partition keys requiring higher limits for storage or throughput, see [Create a synthetic partition key](synthetic-partition-keys.md). If your workload has already reached the logical partition limit of 20GB in production, it is recommended to re-architect your application with a different partition key as a long-term solution. To help give time for this, you can request a temporary increase in the logical partition key limit for your existing application. [File an Azure support ticket](create-support-request-quota-increase.md) and select quota type **Temporary increase in container's logical partition key size**. Note this is intended as a temporary mitigation and not recommended as a long-term solution, as SLA guarantees are not honored when the limit is increased. To remove the configuration, file a support ticket and select quota type **Restore container’s logical partition key size to default (20 GB)**. This can be done after you have either deleted data to fit the 20 GB logical partition limit or have re-architected your application with a different partition key.
 
 ### Minimum throughput limits
 

articles/cosmos-db/create-alerts.md

@@ -5,26 +5,31 @@ author: StefArroyo
 ms.author: esarroyo 
 ms.service: cosmos-db
 ms.topic: how-to
-ms.date: 07/16/2020
+ms.date: 02/08/2022
 ---
 
 # Create alerts for Azure Cosmos DB using Azure Monitor
 [!INCLUDE[appliesto-all-apis](includes/appliesto-all-apis.md)]
 
 Alerts are used to set up recurring tests to monitor the availability and responsiveness of your Azure Cosmos DB resources. Alerts can send you a notification in the form of an  email, or execute an Azure Function when one of your metrics reaches the threshold or if a specific event is logged in the activity log.
 
-You can receive an alert based on the metrics, or the activity log events on your Azure Cosmos account:
+You can receive an alert based on the metrics, activity log events, or Log Analytics logs on your Azure Cosmos account:
 
 * **Metrics** - The alert triggers when the value of a specified metric crosses a threshold you assign. For example, when the total request units consumed exceed 1000 RU/s. This alert is triggered both when the condition is first met and then afterwards when that condition is no longer being met. See the [monitoring data reference](monitor-cosmos-db-reference.md#metrics) article for different metrics available in Azure Cosmos DB.
 
 * **Activity log events** – This alert triggers when a certain event occurs. For example, when the keys of your Azure Cosmos account are accessed or refreshed.
 
+* **Log Analytics** – This alert triggers when the value of a specified property in the results of a Log Analytics query crosses a threshold you assign. For example, you can write a Log Analytics query to [monitor if the storage for a logical partition key is reaching the 20 GB logical partition key storage limit](how-to-alert-on-logical-partition-key-storage-size.md) in Azure Cosmos DB. 
+
 You can set up alerts from the Azure Cosmos DB pane or the Azure Monitor service in the Azure portal. Both the interfaces offer the same options. This article shows you how to set up alerts for Azure Cosmos DB using Azure Monitor.
 
 ## Create an alert rule
 
 This section shows how to create an alert when you receive an HTTP status code 429, which is received when the requests are rate limited. For examples, you may want to receive an alert when there are 100 or more rate limited requests. This article shows you how to configure an alert for such scenario by using the HTTP status code. You can use the similar steps to configure other types of alerts as well, you just need to choose a different condition based on your requirement.
 
+> [!TIP]
+> The scenario of alerting based on number of 429s exceeding a threshold is used here for illustration purposes. It does not mean that there is anything inherently wrong with seeing 429s on your database or container. In general, if you see 1-5% of requests with 429s in a production workload and your overall application latency is within your requirements, this is a normal and healthy sign that you are fully using the throughput (RU/s) you've provisioned. [Learn more about how to interpret and debug 429 exceptions](sql/troubleshoot-request-rate-too-large.md).
+
 1. Sign into the [Azure portal.](https://portal.azure.com/)
 
 1. Select **Monitor** from the left-hand navigation bar and select **Alerts**.
@@ -43,17 +48,17 @@ This section shows how to create an alert when you receive an HTTP status code 4
 
    * After filling in the details, a list of Azure Cosmos accounts in the selected scope is displayed. Choose the one for which you want to configure alerts and select **Done**.
 
-1. Fill out the **Condition** section:
+1. Fill out the **Condition** section: 
 
-   * Open the **Select condition** pane to open the **Configure signal logic** page and configure the following:
+   * Open the **Select condition** pane to open the **Select a signal** page and configure the following:
 
-   * Select a signal. The **signal type** can be a **Metric** or an **Activity Log**. Choose **Metrics** for this scenario. Because you want to get an alert when there are rate limiting issues on the total request units metric.
+   * Select a signal. The **signal type** can be a **Metric**, an **Activity Log** or a **Log** (Log Analytics). Choose **Metrics** for this scenario, as you want to get an alert when rate limiting occurs on the total request units metric.
 
    * Select **All** for the **Monitor service**
 
    * Choose a **Signal name**. To get an alert for HTTP status codes, choose the **Total Request Units** signal.
 
-   * In the next tab, you can define the logic for triggering an alert and use the chart to view trends of your Azure Cosmos account. The **Total Request Units** metric supports dimensions. These dimensions allow you to filter on the metric. If you don’t select any dimension, this value is ignored.
+   * Now, you can define the logic for triggering an alert and use the chart to view trends of your Azure Cosmos account. The **Total Request Units** metric supports dimensions. These dimensions allow you to filter on the metric. For example, you can use dimensions to filter to a specific database or container you want to monitor. If you don't select any dimension, this value is ignored.
 
    * Choose **StatusCode** as the **Dimension name**. Select **Add custom value** and set the status code to 429.
 
@@ -91,6 +96,7 @@ The following are some scenarios where you can use alerts:
 
 * When the keys of an Azure Cosmos account are updated.
 * When the data or index usage of a container, database, or a region exceeds a certain number of bytes.
+* [When the storage for a logical partition key is reaching the Azure Cosmos DB 20 GB logical partition storage limit.](how-to-alert-on-logical-partition-key-storage-size.md)
 * When the normalized RU/s consumption is greater than certain percentage. The normalized RU consumption metric gives the maximum throughput utilization within a replica set. To learn, see the [How to monitor normalized RU/s](monitor-normalized-request-units.md) article.  
 * When a region is added, removed, or if it goes offline.
 * When a database or a container is created, deleted, or updated.

articles/cosmos-db/how-to-alert-on-logical-partition-key-storage-size.md

@@ -0,0 +1,162 @@
+---
+title: Create alerts to monitor if storage for a logical partition key is approaching 20 GB
+description: Learn how to set up alerts for Azure Cosmos DB using Log Analytics
+author: deborahc
+ms.author: dech 
+ms.service: cosmos-db
+ms.topic: how-to
+ms.date: 02/08/2022
+---
+
+# Create alerts to monitor if storage for a logical partition key is approaching 20 GB
+[!INCLUDE[appliesto-all-apis](includes/appliesto-all-apis.md)]
+
+Azure Cosmos DB enforces a maximum logical partition key size of 20 GB. For example, if you have a container/collection partitioned by **UserId**, the data within the "Alice" logical partition can store up to 20 GB of data. 
+
+You can use alerts to monitor if you have any logical partition keys that are approaching the 20 GB logical partition limit. Alerts can send you a notification in the form of an email or execute an action, such as an Azure Function or Logic App, when the condition is triggered.
+
+In this article, we’ll create an alert that will trigger if the storage for a logical partition key exceeds 70% of the 20 GB limit (has more than 14 GB of storage). You can set up alerts from the **Alerts** pane in a specific Azure Cosmos DB account or the **Azure Monitor** service in the Azure portal. Both the interfaces offer the same options. This article shows you how to set up the alert from Azure Monitor. 
+
+## Pre-requisites 
+
+We’ll be using data from the **PartitionKeyStatistics** log category in Diagnostic Logs to create our alert. Diagnostic Logs is an opt-in feature, so you’ll need to enable it before proceeding. In our example, we’ll use the recommended Resource Specific Logs option. 
+
+Follow the instructions in [Monitor Azure Cosmos DB data by using diagnostic settings in Azure](cosmosdb-monitor-resource-logs.md) to ensure:
+- Diagnostic Logs is enabled on the Azure Cosmos DB account(s) you want to monitor
+- You have configured collection of the **PartitionKeyStatistics** log category
+- The Diagnostic logs are being sent to a Log Analytics workspace
+
+
+## Create the alert
+
+1. Sign into the [Azure portal.](https://portal.azure.com/)
+
+1. Select **Monitor** from the left-hand navigation bar and select **Alerts**.
+
+1. Select the New alert rule button to open the Create alert rule pane.  
+
+1. Fill out the **Scope** section:
+
+   * Open the **Select resource** pane and configure the following:
+
+   * Choose your **subscription** name.
+
+   * Select **Azure Cosmos DB accounts** for the **resource type**.
+
+   * The **location** of your Azure Cosmos account.
+
+   * After filling in the details, a list of Azure Cosmos accounts in the selected scope is displayed. Choose the one for which you want to configure alerts and select **Done**.
+
+1. Fill out the **Condition** section: 
+
+   * Open the **Select condition** pane to open the **Select a signal** page and configure the following:
+
+   * Select **Log** for the **Signal type**.
+
+   * Select **Log analytics** for the **Monitor service**.
+
+   * Select **Custom log search** for the **Signal name**.
+
+   * In the query editor, add the below query. You can run the query to preview the result. 
+    > [!NOTE]
+    > It's perfectly ok if the query currently returns no results. The **PartitionKeyStatistics** logs only show data if there are logical partition keys with significant storage size, so if there are no results returned, it means that there are no such keys. If and when such keys do appear in the future, the alert will be triggered then.
+
+    ```kusto
+    CDBPartitionKeyStatistics
+    // Get the latest storage size for each logical partition key value
+    | summarize arg_max(TimeGenerated, *) by AccountName, DatabaseName, CollectionName, _ResourceId, PartitionKey 
+    | extend utilizationOf20GBLogicalPartition = SizeKb / (20.0 * 1024.0 * 1024.0) // Current storage / 20GB
+    | project TimeGenerated, AccountName, DatabaseName, CollectionName, _ResourceId, PartitionKey, SizeKb, utilizationOf20GBLogicalPartition
+    ```
+   * Select **Continue Editing Alert**.
+
+   * In the Measurement section:
+
+        * Select **utilizationOf20GBLogicalPartition** for **Measure**.
+
+        * Select **Maximum** for **Aggregation type**.
+
+        * Select your desired **Aggregation granularity** based on your requirements. In our example, we’ll select **1 hour**. This means that the alert will calculate the storage size of the logical partition using the highest storage value in the hour. 
+
+   * In the Split by dimensions section:
+
+        * Add the following six dimensions: **AccountName**, **DatabaseName**, **CollectionName**, **_ResourceId**, **PartitionKey**, **SizeKb**. This ensures that when the alert is triggered, you’ll be able to identify the specific Azure Cosmos DB account, database, collection, and partition key that triggered the alert.
+
+        * For the **SizeKb** dimension, select **Select all current and future values** as the **Dimension values**. 
+
+        * For all other dimensions:
+            * If you want to monitor only a specific Azure Cosmos DB account, database, collection, or partition key, select the specific value or **Add custom value** if the value doesn’t currently appear in the dropdown.  
+
+            * Otherwise, select **Select all current and future values**. For example, if your Cosmos account currently has two databases and five collections, selecting all current and feature values for the Database and CollectionName dimension will ensure that the alert will apply to all existing databases and collections, as well as any you may create in the future. 
+
+   * In the Alert logic section:
+
+        * Select **Greater than** for **Operator**.
+
+        * Select your desired threshold value. Based on how we’ve written the query, a valid threshold will be a number between 0 and 1 (inclusive). In our example, we want to trigger the alert if a logical partition key reaches 70% of the allowed storage, so we enter **0.7**. You can tune this number based on your requirements.
+
+        * Select your desired **Frequency of evaluation** based on your requirements. In our example, we’ll select **1 hour**. Note this value must be less than or equal to the alert evaluation period.
+
+        After completing Step 5, the **Condition** section will look like the example below. 
+    
+        :::image type="content" source="media/how-to-alert-on-logical-partition-key-storage-size/alert-signal-logic.png" alt-text="Screenshot of an example configuration for signal logic":::
+
+1. Fill out the **Actions** section:
+
+   * Select an existing action group or create a new action group. An action group enables you to define the action(s) to be taken when the alert is triggered. For this example, create a new action group to receive an email notification when the alert is triggered. Open the **Create action group** pane.
+
+    * In the **Basics** section:
+
+        * Choose the subscription and the resource group in which this action group will be created.  
+        
+        * **Action group name** - The action group name must be unique within a resource group.
+        
+        * **Display name** - This value is included in email and SMS notifications to identify which action group was the source of the notification.
+
+    * In the **Notifications** section:
+
+        * Provide a name for your notification.
+
+        * Select **Email/SMS message/Push/Voice** as the **Notification Type** and enter your email, SMS, Push Notification, or Voice information. 
+    * Optional: In the **Actions** section, you can select an **Action** that will be run, such as an Azure Function or Logic App in the **Actions** section.
+    * Select **Review + create** to create the Action Group.
+
+1. Fill out the **Details** section:
+
+   * Define a name for the alert, provide an optional description, the severity level of the alert, and choose whether to enable the rule upon rule creation.
+   * Select **Review + create** and select **Create** to finish creating the alert.
+
+After creating the alert, it will be active within 10 minutes.
+
+## Example alert
+To see your alerts in the Azure portal:
+
+1. Sign into the [Azure portal.](https://portal.azure.com/)
+
+1. Select **Monitor** from the left-hand navigation bar and select **Alerts**.
+
+When the alert is fired, it will include:
+- Database account name
+- Database name
+- Collection name
+- Logical partition key
+- Storage in KB of the logical partition key
+- Utilization of the 20 GB limit
+
+For example, in the alert that was fired below, we see the logical partition of "ContosoTenant" has reached 0.78 of the 20GB logical partition storage limit, with 16GB of data in a particular database and collection. 
+
+:::image type="content" source="media/how-to-alert-on-logical-partition-key-storage-size/alert-when-logical-partition-key-exceeds-threshold.png" alt-text="Screenshot of an alert fired when logical partition key size exceeds threshold":::
+
+## Remediation steps
+When the 20 GB logical partition size limit is reached, you won't be able to write any more data to that logical partition. As a result, it's recommended to rearchitect your application with a different partition key as a long-term solution. 
+
+To help give time for this, you can request a temporary increase in the logical partition key limit for your existing application.  [File an Azure support ticket](create-support-request-quota-increase.md) and select quota type **Temporary increase in container's logical partition key size.** Note this is intended as a temporary mitigation and not recommended as a long-term solution, as SLA guarantees are not honored when the limit is increased. To remove the configuration, file a support ticket and select quota type **Restore container’s logical partition key size to default (20 GB)**. This can be done after you have either deleted data to fit the 20 GB logical partition limit or have rearchitected your application with a different partition key.
+
+To learn about best practices for managing workloads that have partition keys requiring higher limits for storage or throughput, see [Create a synthetic partition key](synthetic-partition-keys.md).
+
+## Next steps
+* How to [create alerts for Azure Cosmos DB using Azure Monitor](create-alerts.md).
+* How to [monitor normalized RU/s metric](monitor-normalized-request-units.md) in Azure Cosmos container.
+* How to [monitor throughput or request unit usage](monitor-request-unit-usage.md) of an operation in Azure Cosmos DB.
+* How to [interpret and debut 429 exceptions](sql/troubleshoot-request-rate-too-large.md) in Azure Cosmos container.
+