How to retrieve the usage details of CosmosDB for adjusting the throughput

In common scenarios, if a server happens to meet short-time high loads, Azure CosmosDB will response with 429 status code. If you are using Azure CosmosDB SDK, the SDK will get the waiting time from the header and will implicitly retry the former request.

However, if the server is just meeting long-time high loads or there are several clients, exceptions might be thrown out. At the time, we can catch this exception and scale up the throughput to a higher level to handle the long-time high loads. For how to adjust the throughput, you can refer to: Modifying the throughput of the Azure Cosmos DB container through the Java SDK

The long-time high loads will not stay forever, so we need to determine when to scale down the throughput to a normal level. Happily, we can monitor the usage details with Azure REST API.

Get token

You can create Azure service principal either through PowerShell or the portal. Then you can get the token for authentication. Here is a sample code:

public static void postForm() { 
 CloseableHttpClient httpclient = HttpClients.createDefault(); 
 HttpPost httppost = new HttpPost("{your tenant id}/oauth2/token?api-version=1.0"); 
 List<NameValuePair> formparams = new ArrayList<NameValuePair>(); 
 formparams.add(new BasicNameValuePair("grant_type", "client_credentials")); 
 formparams.add(new BasicNameValuePair("resource", "")); 
 formparams.add(new BasicNameValuePair("client_id", "{your client id}")); 
 formparams.add(new BasicNameValuePair("client_secret", " your client secret")); 
 UrlEncodedFormEntity uefEntity; 
 try { 
 uefEntity = new UrlEncodedFormEntity(formparams, "UTF-8"); 
 CloseableHttpResponse response = httpclient.execute(httppost); 
 try { 
 HttpEntity entity = response.getEntity(); 
 if (entity != null) { 
 System.out.println(EntityUtils.toString(entity, "UTF-8")); //A Json which contains the access_token 
 } finally { 
 } catch (Exception e) { 
 } finally { 
 try { 
 } catch (IOException e) { 

Retrieve the usage details

Make Http Get request, here is the request URL format:



Authorization: Bearer {access_token}

The “databaseRid” and “collectionRid” are generated by system. The “filter” is an OData filter expression that describes a subset of metrics to return. The following is a successful request sample:$filter=(name.value eq ‘Max RUs Per Second’) and startTime eq 2018-01-09T07:25:00.000Z and endTime eq 2018-01-09T07:30:00.000Z and timeGrain eq duration’PT1M’

You will get a Json response:

   "timeGrain": "PT1M",
   "startTime": "2018-01-09T07:25:00.0000000Z",
   "endTime": "2018-01-09T07:30:00.0000000Z",
   "unit": "Count",
    {"timestamp": "2018-01-09T07:25:00.0000000Z", "maximum": 510, "total": 510, "_count": 510…},
    {"timestamp": "2018-01-09T07:26:00.0000000Z", "maximum": 490, "total": 490, "_count": 490…},
    {"timestamp": "2018-01-09T07:27:00.0000000Z", "maximum": 500, "total": 500, "_count": 500…},
    {"timestamp": "2018-01-09T07:28:00.0000000Z", "maximum": 480, "total": 480, "_count": 480…},
    {"timestamp": "2018-01-09T07:29:00.0000000Z", "maximum": 495, "total": 495, "_count": 495…}
   "value": "Max RUs Per Second",
   "localizedValue": "Max RUs Per Second"

From the Json, you can clearly see the RU records during the periods. You can determine  whether to adjust the RU or not by comparing it with the Max RU you set before.


This article is about how to retrieve the usage details of CosmosDB for adjusting the throughput via Azure REST API If you have any other questions, please contact us via .

Leave a Reply

Your email address will not be published. Required fields are marked *