updates to control plane service limits.

Author: markjbrown

articles/cosmos-db/concepts-limits.md

@@ -7,7 +7,7 @@ ms.author: sidandrews
 ms.reviewer: mjbrown
 ms.service: cosmos-db
 ms.topic: conceptual
-ms.date: 02/27/2023
+ms.date: 04/15/2023
 ms.custom: ignite-2022
 ---
 
@@ -93,18 +93,46 @@ Depending on the current RU/s provisioned and resource settings, each resource c
 
 ¹ Serverless containers up to 1 TB are currently in preview with Azure Cosmos DB. To try the new feature, register the *"Azure Cosmos DB Serverless 1 TB Container Preview"* [preview feature in your Azure subscription](../azure-resource-manager/management/preview-features.md).
 
-## Control plane operations
+## Control plane
 
-You can [create and manage your Azure Cosmos DB account](how-to-manage-database-account.md) using the Azure portal, Azure PowerShell, Azure CLI, and Azure Resource Manager templates. The following table lists the limits per subscription, account, and number of operations.
+Azure Cosmos DB maintains a resource provider that offers a management layer to create, update, and delete resources in your Azure Cosmos DB account. The resource provider interfaces with the overall Azure Resource Management layer, which is the deployment and management service for Azure. You can [create and manage Azure Cosmos DB resources](how-to-manage-database-account.md) using the Azure portal, Azure PowerShell, Azure CLI, Azure Resource Manager and Bicep templates, Rest API, Azure Management SDKs as well as 3rd party tools such as Terraform and Pulumi.
+
+This management layer can also be accessed from the Azure Cosmos DB data plane SDKs used in your applications to create and manage resources within an account. Data plane SDKs also make control plane requests during inital connection to the service to do things like enumerating databases and containers, as well as requesting account keys for authentication.
+
+Each account for Azure Cosmos DB has a `master partition` which contains all of the metadata for an account. It also has a small amount of throughput to support control plane operations. Control plane requests that create, read, update or delete this metadata consumes this throughput. When the amount of throughput consumed by control plane operations exceeds this amount, operations are rate-limited, same as data plane operations within Azure Cosmos DB. However, unlike throughput for data operations, throughput for the master partition cannot be increased.
+
+Some control plane operations do not consume master partition throughput, such as Get or List Keys. However, unlike requests on data within your Azure Cosmos DB account, resource providers within Azure are not designed for high request volumes. **Control plane operations that exceed the documented limits at sustained levels over consecutive 5-minute periods here may experience request throttling as well failed or incomplete operations on Azure Cosmos DB resources**. 
+
+Control plane operations can be monitored by navigating the the Insights tab for an Azure Cosmos DB account. To learn more see [Monitor Control Plane Requests](use-metrics.md#Monitor-control-plane-requests). Users can also customize these use Azure Monitor and create a workbook to monitor [Metadata Requests](monitor-reference.md#request-metrics) and set alerts on them.
+
+### Resource limits
+
+The following table lists resource limits per subscription or account.
 
 | Resource | Limit |
 | --- | --- |
 | Maximum number of accounts per subscription | 50 by default. ¹ |
-| Maximum number of regional failovers | 10/hour by default. ¹ ² |
+| Maximum number of databases & containers per account | 500 ² |
+| Maximum throughput supported by an account for metadata operations | 240 RU/s |
 
 ¹ You can increase these limits by creating an [Azure Support request](create-support-request-quota-increase.md) up to 1,000 max.
+² This limit cannot be increased. Total count of both with an account. (1 database and 499 containers, 250 databases and 250 containers, etc.)
+
+### Request limits
+
+The following table lists request limits per 5 minute interval, per account, unless otherwise specified.
+
+| Operation | Limit |
+| --- | --- |
+| Maximum List or Get Keys | 500 ¹ | 
+| Maximum Create database & container | 500 |
+| Maximum Get or List database & container | 500 ¹ |
+| Maximum Update provisioned throughput | 25 |
+| Maximum regional failover | 10 (per hour) ² |
+| Maximum number of all operations (PUT, POST, PATCH, DELETE, GET) not defined above | 100 |
 
-² Regional failovers only apply to single region writes accounts. Multi-region write accounts don't require or have any limits on changing the write region.
+¹ Users should use [singleton client](nosql/best-practice-dotnet.md#checklist) for SDK instances and cache keys and database and container references between requests for the lifetime of that instance.
+² Regional failovers only apply to single region writes accounts. Multi-region write accounts don't require or allow changing the write region.
 
 Azure Cosmos DB automatically takes backups of your data at regular intervals. For details on backup retention intervals and windows, see [Online backup and on-demand data restore in Azure Cosmos DB](online-backup-and-restore.md).
 
@@ -116,17 +144,15 @@ Here's a list of limits per account.
 
 | Resource | Limit |
 | --- | --- |
-| Maximum number of databases per account | 500 |
-| Maximum number of containers per database with shared throughput |25 |
-| Maximum number of containers per account | 500 |
+| Maximum number of databases and containers per account | 500 |
+| Maximum number of containers per database with shared throughput | 25 |
 | Maximum number of regions | No limit (All Azure regions) |
 
 ### Serverless
 
 | Resource | Limit |
 | --- | --- |
-| Maximum number of databases per account  | 100 |
-| Maximum number of containers per account  | 100 |
+| Maximum number of databases and containers per account  | 100 |
 | Maximum number of regions | 1 (Any Azure region) |
 
 ## Per-container limits
@@ -178,6 +204,8 @@ Azure Cosmos DB supports [CRUD and query operations](/rest/api/cosmos-db/) again
 | Maximum response size (for example, paginated query) | 4 MB |
 | Maximum number of operations in a transactional batch | 100 |
 
+Azure Cosmos DB supports execution of triggers during writes. The service supports a maximum of one pre-trigger and one post-trigger per write operation.
+
 Once an operation like query reaches the execution timeout or response size limit, it returns a page of results and a continuation token to the client to resume execution. There's no practical limit on the duration a single query can run across pages/continuations.
 
 Azure Cosmos DB uses HMAC for authorization. You can use either a primary key, or a [resource token](secure-access-to-data.md) for fine-grained access control to resources. These resources can include containers, partition keys, or items. The following table lists limits for authorization tokens in Azure Cosmos DB.
@@ -191,19 +219,6 @@ Azure Cosmos DB uses HMAC for authorization. You can use either a primary key, o
 
 ¹ You can increase it by [filing an Azure support ticket](create-support-request-quota-increase.md)
 
-Azure Cosmos DB supports execution of triggers during writes. The service supports a maximum of one pre-trigger and one post-trigger per write operation.
-
-## Metadata request limits
-
-Azure Cosmos DB maintains system metadata for each account. This metadata allows you to enumerate collections, databases, other Azure Cosmos DB resources, and their configurations for free of charge.
-
-| Resource | Limit |
-| --- | --- |
-|Maximum collection create rate per minute|    100|
-|Maximum Database create rate per minute|    100|
-|Maximum provisioned throughput update rate per minute|    5|
-|Maximum throughput supported by an account for metadata operations | 240 RU/s |
-
 ## Limits for autoscale provisioned throughput
 
 See the [Autoscale](provision-throughput-autoscale.md#autoscale-limits) article and [FAQ](autoscale-faq.yml#lowering-the-max-ru-s) for more detailed explanation of the throughput and storage limits with autoscale.
@@ -241,13 +256,16 @@ The following table lists the limits specific to MongoDB feature support. Other
 
 | Resource | Limit |
 | --- | --- |
+| Maximum size of a document | 16 MB (UTF-8 length of JSON representation) ¹ |
 | Maximum MongoDB query memory size (This limitation is only for 3.2 server version) | 40 MB |
 | Maximum execution time for MongoDB operations (for 3.2 server version)| 15 seconds|
 | Maximum execution time for MongoDB operations (for 3.6 and 4.0 server version)| 60 seconds|
 | Maximum level of nesting for embedded objects / arrays on index definitions | 6 |
-| Idle connection timeout for server side connection closure ¹ | 30 minutes |
+| Idle connection timeout for server side connection closure ² | 30 minutes |
+
+¹ Large document sizes up to 16 MB require feature enablement in Azure Portal. Read the [feature documentation](../cosmos-db/mongodb/feature-support-42.md#data-types) to learn more.
 
-¹ We recommend that client applications set the idle connection timeout in the driver settings to 2-3 minutes because the [default timeout for Azure LoadBalancer is 4 minutes](../load-balancer/load-balancer-tcp-idle-timeout.md).  This timeout ensures that an intermediate load balancer idle doesn't close connections between the client machine and Azure Cosmos DB.
+² We recommend that client applications set the idle connection timeout in the driver settings to 2-3 minutes because the [default timeout for Azure LoadBalancer is 4 minutes](../load-balancer/load-balancer-tcp-idle-timeout.md).  This timeout ensures that an intermediate load balancer idle doesn't close connections between the client machine and Azure Cosmos DB.
 
 ## Try Azure Cosmos DB Free limits
 

articles/cosmos-db/how-to-manage-database-account.md

@@ -6,7 +6,7 @@ ms.service: cosmos-db
 ms.subservice: nosql
 ms.custom: ignite-2022, devx-track-arm-template
 ms.topic: how-to
-ms.date: 03/08/2023
+ms.date: 04/14/2023
 ms.author: sidandrews
 ms.reviewer: mjbrown
 ---
@@ -15,10 +15,10 @@ ms.reviewer: mjbrown
 
 [!INCLUDE[NoSQL, MongoDB, Cassandra, Gremlin, Table](includes/appliesto-nosql-mongodb-cassandra-gremlin-table.md)]
 
-This article describes how to manage various tasks on an Azure Cosmos DB account by using the Azure portal.
+This article describes how to manage various tasks on an Azure Cosmos DB account by using the Azure portal. Azure Cosmos DB can also be managed with other Azure management clients including [Azure PowerShell](manage-with-powershell.md), [Azure CLI](nosql/manage-with-cli.md), [Azure Resource Manager templates](./manage-with-templates.md), [Bicep](nosql/manage-with-bicep.md), and [Terraform](nosql/samples-terraform.md).
 
 > [!TIP]
-> Azure Cosmos DB can also be managed with other Azure management clients including [Azure PowerShell](manage-with-powershell.md), [Azure CLI](sql/manage-with-cli.md), [Azure Resource Manager templates](./manage-with-templates.md), and [Bicep](sql/manage-with-bicep.md).
+> The management API for Azure Cosmos DB or *control plane* is not designed for high request volumes like the rest of the service. To learn more see [Control Plane Service Limits](concepts-limits.md#control-plane)
 
 ## Create an account
 
@@ -108,6 +108,7 @@ After an Azure Cosmos DB account is configured for service-managed failover, the
 
    :::image type="content" source="./media/how-to-manage-database-account/manual-failover.png" alt-text="Screenshot of the manual failover portal menu.":::
 
+
 ## Next steps
 
 For more information and examples on how to manage the Azure Cosmos DB account as well as databases and containers, read the following articles:

articles/cosmos-db/media/use-metrics/metadata-requests-429.png

@@ -5,7 +5,7 @@ ms.author: esarroyo
 author: StefArroyo 
 ms.service: cosmos-db
 ms.topic: how-to
-ms.date: 12/07/2020
+ms.date: 04/14/2023
 ms.custom: subject-monitoring, ignite-2022
 ---
 
@@ -24,7 +24,7 @@ All the metrics corresponding to Azure Cosmos DB are stored in the namespace **A
 |Metric (Metric Display Name)|Unit (Aggregation Type) |Description|Dimensions| Time granularities| Legacy metric mapping | Usage |
 |---|---|---|---| ---| ---| ---|
 | TotalRequests (Total Requests) | Count (Count) | Number of requests made| DatabaseName, CollectionName, Region, StatusCode| All | TotalRequests, Http 2xx, Http 3xx, Http 400, Http 401, Internal Server error, Service Unavailable, Throttled Requests, Average Requests per Second | Used to monitor requests per status code, container at a minute granularity. To get average requests per second, use Count aggregation at minute and divide by 60. |
-| MetadataRequests (Metadata Requests) |Count (Count) | Count of metadata requests. Azure Cosmos DB maintains system metadata container for each account, that allows you to enumerate collections, databases, etc., and their configurations, free of charge. | DatabaseName, CollectionName, Region, StatusCode| All| |Used to monitor throttles due to metadata requests.|
+| MetadataRequests (Metadata Requests) |Count (Count) | Count of ARM metadata requests. Metadata has request limits. See [Control Plane Limits](concepts-limits.md#control-plane) for more information. | DatabaseName, CollectionName, Region, StatusCode| All | | Used to monitor metadata requests in scenarios where requests are being throttled. See [Monitor Control Plane Requests](use-metrics.md#Monitor-control-plane-requests) for more information. |
 | MongoRequests (Mongo Requests) | Count (Count) | Number of Mongo Requests Made | DatabaseName, CollectionName, Region, CommandName, ErrorCode| All |Mongo Query Request Rate, Mongo Update Request Rate, Mongo Delete Request Rate, Mongo Insert Request Rate, Mongo Count Request Rate| Used to monitor Mongo request errors, usages per command type. |
 
 ### Request Unit metrics

articles/cosmos-db/media/use-metrics/metadata-requests-by-status-code.png

@@ -7,7 +7,7 @@ ms.reviewer: mjbrown
 ms.service: cosmos-db
 ms.subservice: nosql
 ms.topic: how-to
-ms.date: 03/13/2023
+ms.date: 04/14/2023
 ms.custom: devx-track-csharp, ignite-2022
 ---
 
@@ -108,6 +108,21 @@ 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 apply the indexes. This problem can be resolved with a better filter condition.
 
+## Monitor control plane requests
+
+Azure Cosmos DB applies limits on the number of metadata requests that can be made over consecutive 5 minute intervals. Control plane requests which go over these limits may experience throttling. Metadata requests may in some cases, consume throughput against a `master partition` within an account that contains all of an account's metadata. Control plane requests which go over the throughput amount will experience rate limiting (429s).
+
+To get started, head to the [Azure portal](https://portal.azure.com) and navigate to the **Insights** pane. From this pane, open the **System** tab. The System tab shows two charts. One that shows all metadata requests for an account. The second shows metadata requests throughput consumption from the account's `master partition` that stores an account's metadata.
+
+:::image type="content" source="media/use-metrics/metadata-requests-by-status-code.png" alt-text="Screenshot of the Insights pane, highlighting the metadata requests graph on the System tab." lightbox="media/use-metrics/metadata-requests-by-status-code.png" :::
+
+:::image type="content" source="media/use-metrics/metadata-requests-429.png" alt-text="Screenshot of the Insights pane, highlighting the metadata requests 429 graph on the System tab." lightbox="media/use-metrics/metadata-requests-429.png" :::
+
+The Metadata Request by Status Code graph above aggregates requests at increasing larger granularity as you increase the Time Range. The largest Time Range you can use for a 5 minute time bin is 4 hours. To monitor metadata requests over a greater time range with specific granularity, use Azure Metrics. Create a new chart and select Metadata requests metric. In the upper right corner select 5 minutes for Time granularity as seen below. Metrics also allow for users to [Create Alerts](create-alerts.md) on them which makes them more useful than Insights.
+
+:::image type="content" source="media/use-metrics/metadata-requests-metrics.png" alt-text="Screenshot of Metrics pane, highlighting the metadata requests for an account and time granularity of 5 minutes." lightbox="media/use-metrics/metadata-requests-429.png" :::
+
+
 ## Next steps
 
 You might want to learn more about improving database performance by reading the following articles: