Load test with Apache JMeter™ against Azure Cosmos DB (SQL API)

How to load test the Azure Cosmos DB with Apache JMeter™.

Apache JMeter™ can also perform load testing against Azure Cosmos DB (SQL API).
Here’s how to set it up.

Quick explanation

Azure Cosmos DB (SQL API) is operated by the REST API.
So, it will be tested using the HTTP request sampler in Apache JMeter™.

For the request to be successful, it must be made with the appropriate method, header, and body.

This tutorial is a test of Azure Cosmos DB against SampleDB.


  1. Firewall configuration of Cosmos DB
    In Cosmos DB, under “Firewall and virtual networks”, allow access from JMeter.
    If you will make SampleDB, you should also “+ Add my current IP (xxx.xxx.xxx.xxx)”.
    Firewall and virtual networks
    The example in this image allows access from JMeter in the client subnet contained in the jmeter-vnet virtual network.
  2. Create SampleDB for Cosmos DB
    In this article, create a test plan against the SampleDB of Cosmos DB to test it.
    In Cosmos DB, under “Data Explorer”, click “Start with Sample”.
    A SampleDB database and a Persons container will be created, and four documents will be registered to it.
    Create SampleDB

    In Cosmos DB’s “Firewall and Virtual Network Settings”, if you do not allow access from the PC operating Azure Portal, creation may fail.

Outline of steps

  1. Install plugin for Microsoft Azure
  2. Add Cosmos DB hostname, key, and other variables
  3. Add a Thread Group
  4. Add a HTTP Request sampler
  5. Add parameters for the data being request
  6. Add a HTTP Header Manager
  7. Add listeners to see the results of the execution
  8. Run the test plan and check the result

Details of steps

  1. Install plugin for Microsoft Azure
    Introduce a function plugin to create an Authorization header to make a request to Cosmos DB.

    1. Get the plugin
      Get the latest plugins (jmeter-plugins-functions-azure-{version}.jar) from the following page using a web browser.
    2. Copy the downloaded jar file to $JMETER_HOME/lib/ext
    3. Start or restart JMeter
  2. Add Cosmos DB hostname, key, and other variables
    Add “User Defined Variables” to the Test Plan and set up variables such as the host name of Cosmos DB.
    Add > Config Element > User Defined Variables

    “User Defined Variables” shows two of the same notation, but probably the upper one.
    If you add it, you will see three columns of “Name, Value, Description” in the header of that table.

    User Defined Variables

    • cosmosdb.Host: Hostname of Cosmos DB (***.documents.azure.com)
    • cosmosdb.Key: Key of Cosmos DB
      You can use either the primary or secondary key.
      A read-only key can also be used to perform a read-only test.
    • headers.x-ms-version: Version of CosmosDB REST service. (ex. 2018-12-31)
      The versions that can be specified here are listed under Support REST API Versions.

    The names of variables here and below are examples, and can be any variable name as long as the definition matches the reference.

  3. Add a Thread Group
    Add a “Thread Group” to the Test Plan.
    Add > Threads (Users) > Thread Group

  4. Add a HTTP Request sampler
    Add a “HTTP Request” samplerj to the added Thread Group.
    Add > Sampler > HTTP Request
    HTTP Request sampler

    • Web Server
      • Protocol [http]: https
      • Server Name or IP: ${cosmosdb.Host}
    • HTTP Request
      • Method: ${request.method}
      • Path: ${request.path}
  5. Add parameters for the data being request
    Add “User Parameters” pre prosessor to the HTTP Request sampler and set the conditions for the data to be requested.
    Add > Pre Processors > User Parameters
    Request Parameters In this tutorial get a list of documents in the Persons container.

    • Parameters

      • cosmosdb.ResourceType: Resource type of request target. [dbs, colls, docs] (ex. docs)
      • cosmosdb.ResourceLink: Resource ID of request target. (ex. dbs/SampleDB/colls/Persons)
      • request.path: Path of request. (ex. /dbs/SampleDB/colls/Persons/docs)
      • request.method: Method of request. (ex. GET)
      • headers.Content-Type: Content-Type header of request: [application/json, application/query+json] (ex. application/json)

      Reference) Common tasks using the Azure Cosmos DB REST API

      To add a value to Parameters, click [Add Variable] and enter a variable name in “Name” and a value in “User_1”.

  6. Add a HTTP Header Manager
    Add a “HTTP Header Manager” to the HTTP Request sampler.
    The headers to be sent will vary depending on the request operation and conditions, but in this example, the following are the headers to be sent.
    Add > Config Element > HTTP Header Manager
    HTTP Header Manager

    • Headers Stored in the Header Manager
      • x-ms-version: ${headers.x-ms-version}
      • Authorization: ${__AzCosmosDbAuthZ(${cosmosdb.Key},headers.x-ms-date,${request.method},${cosmosdb.ResourceType},${cosmosdb.ResourceLink})}
      • Content-Type: ${headers.Content-Type}
      • x-ms-max-item-count: -1
      • x-ms-date: ${headers.x-ms-date}
  7. Add listeners to see the results of the execution
    Add a “View Results Tree” listener to the Test Plan or thread group.
    Add > Listener > View Results Tree

  8. Run the test plan and check the result
    Run > Start to run the test and select the resulting “HTTP Request” and then select the “Response Body” tab on the “Response data” tab.
    This is where the JSON data of the response is displayed.
    View Results Tree

So far, we have confirmed that we can test to Azure Cosmos DB.
Next, create a request to execute SQL.

  1. Copy the HTTP Request sampler
    Copy (right click > Copy or Ctrl+C) the “HTTP Request” that you just made, and paste (right click > Paste or Ctrl+P) it into the Thread Group.

    “HTTP Request”, “User Parameters” and “HTTP Header Manager” will be added.

  2. Update HTTP Request
    Enter ${request.body} in the “Body Data” tab.
    HTTP Request

  3. Update User Parameters
    Add or update some parameters.
    Request Parameters

    • request.method (Updated): POST
    • headers.Content-Type (Updated): application/query+json
    • request.body (Added): SQL and parameters to execute. (ex. {“query”: “SELECT * FROM c WHERE c.age = 23”, “parameters”: []}
  4. Update HTTP Header Manager
    Add some HTTP headers.
    HTTP Header Manager

    • x-ms-documentdb-isquery: true
    • x-ms-documentdb-query-enablecrosspartition: true

    Set the appropriate request header according to the SQL to be executed and other conditions.
    Reference) Common Azure Cosmos DB REST request headers

  5. Run the test plan and check the result
    Run > Start to run the test.
    Two HTTP Requests are output to the View Results Tree to get the response data for the request.

The sample jmx file created in this tutorial.

That’s it, this article has introduced the basic way to test to Azure Cosmos DB in Apache JMeter™.

[ad] Easily build a JMeter multiple remote servers environment in Azure by Load Tester Powered by Apache JMeter™