Merge pull request #234594 from markjbrown/control-plane-throttling-limits

Control plane throttling limits

Author: JamesJBarnett

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 initial 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 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 | 500 |
 
-² 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/how-to-setup-rbac.md

@@ -3,11 +3,11 @@ title: Configure role-based access control with Azure AD
 titleSuffix: Azure Cosmos Db
 description: Learn how to configure role-based access control with Azure Active Directory for your Azure Cosmos DB account
 author: seesharprun
+ms.service: cosmos-db
+ms.topic: how-to
+ms.date: 04/14/2023
 ms.author: sidandrews
 ms.reviewer: mjbrown
-ms.service: cosmos-db
-ms.topic: conceptual
-ms.date: 02/27/2023
 ms.custom: ignite-2022
 ---
 
@@ -39,11 +39,10 @@ The Azure Cosmos DB data plane role-based access control is built on concepts th
 ## <a id="permission-model"></a> Permission model
 
 > [!IMPORTANT]
-> This permission model covers only database operations that involve reading and writing data. It does *not* cover any kind of management operations on management resources, for example:
->
+> This permission model covers only database operations that involve reading and writing data. It **does not** cover any kind of management operations on management resources, including:
 > - Create/Replace/Delete Database
 > - Create/Replace/Delete Container
-> - Replace Container Throughput
+> - Read/Replace Container Throughput
 > - Create/Replace/Delete/Read Stored Procedures
 > - Create/Replace/Delete/Read Triggers
 > - Create/Replace/Delete/Read User Defined Functions
@@ -91,7 +90,7 @@ The Azure Cosmos DB SDKs issue read-only metadata requests during initialization
 - The partition key of your containers or their indexing policy.
 - The list of physical partitions that make a container and their addresses.
 
-They don't* fetch any of the data that you've stored in your account.
+They **do not** fetch any of the data that you've stored in your account.
 
 To ensure the best transparency of our permission model, these metadata requests are explicitly covered by the `Microsoft.DocumentDB/databaseAccounts/readMetadata` action. This action should be allowed in every situation where your Azure Cosmos DB account is accessed through one of the Azure Cosmos DB SDKs. It can be assigned (through a role assignment) at any level in the Azure Cosmos DB hierarchy (that is, account, database, or container).
 
@@ -103,6 +102,9 @@ The actual metadata requests allowed by the `Microsoft.DocumentDB/databaseAccoun
 | Database | &bull; Reading database metadata <br /> &bull; Listing the containers under the database <br /> &bull; For each container under the database, the allowed actions at the container scope |
 | Container | &bull; Reading container metadata <br /> &bull; Listing physical partitions under the container <br /> &bull; Resolving the address of each physical partition |
 
+> [!IMPORTANT] 
+> Throughput is not included in the metadata for this action.
+
 ## Built-in role definitions
 
 Azure Cosmos DB exposes two built-in role definitions:

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 Azure Resource Manager 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
@@ -90,7 +90,7 @@ The following table lists the properties of resource logs in Azure Cosmos DB. Th
 | **duration** | **duration_d** | The duration of the operation, in milliseconds. |
 | **requestLength** | **requestLength_s** | The length of the request, in bytes. |
 | **responseLength** | **responseLength_s** | The length of the response, in bytes.|
-| **resourceTokenPermissionId** | **resourceTokenPermissionId_s** | This property indicates the resource token permission Id that you have specified. To learn more about permissions, see the [Secure access to your data](./secure-access-to-data.md#permissions) article. |
+| **resourceTokenPermissionId** | **resourceTokenPermissionId_s** | This property indicates the resource token permission ID that you have specified. To learn more about permissions, see the [Secure access to your data](./secure-access-to-data.md#permissions) article. |
 | **resourceTokenPermissionMode** | **resourceTokenPermissionMode_s** | This property indicates the permission mode that you have set when creating the resource token. The permission mode can have values such as "all" or "read". To learn more about permissions, see the [Secure access to your data](./secure-access-to-data.md#permissions) article. |
 | **resourceTokenUserRid** | **resourceTokenUserRid_s** | This value is non-empty when [resource tokens](./secure-access-to-data.md#resource-tokens) are used for authentication. The value points to the resource ID of the user. |
 | **responseLength** | **responseLength_s** | The length of the response, in bytes.|