Azure Cosmos DB NoSQL - Load Test (alpha version)

Introduction

Cosmos Load Test enables you to try/benchmark Azure Cosmos DB for NoSQL using your own entities. This guide will help you configure the config.json file for the cosmos-loadtest project.

Prerequisites

A text editor
A Cosmos DB account
A Cosmos DB database and container
.NET Runtime 6.0

Steps

Download the latest release from here.
Extract cosmos-loadtest_v0.2.zip and open the config.json file in your text editor.
Configure the parameters according to your requirements (options detailed below).
Run cosmos-loadtest.exe.

For better performance, run the load tester in a VM in the same Azure Region as your Azure Cosmos DB account.

Attribute provided as partition key MUST be of type string.

Configuration Options

Attribute	Type	Description	Required
cosmosConnection	string	Connection string of your Cosmos DB account	yes
databaseName	string	Database name	yes
containerName	string	Container Name	yes
preferredRegions	array	Array of strings. If using multi region account, use to set the preferred region	no
durationSec	integer	Test duration in seconds	yes
printClientStats	boolean	Flag to print client statistics (noisy in massive tests)	yes
printResultRecord	boolean	Flag to print the results either for queries or creates/upserts (noisy in massive tests)	yes
loadConfig	array	Array of tests to run	yes

Query Options

Attribute	Type	Description	Required
taskCount	integer	Number of concurrent tasks to run	yes
intervalMS	integer	Interval/delay between interations within the same task	yes
applicationName	string	Application name used for CosmosClient. Helpful for tracing using Diagnostic Settings	no
query.text	string	Your query to be executed. Include parameters to bind.	yes
query.parameters	array	Array of parameters to bind in query	yes if query has any

Point Read Options

Attribute	Type	Description	Required
taskCount	integer	Number of concurrent tasks to run	yes
intervalMS	integer	Interval/delay between interations within the same task	yes
applicationName	string	Application name used for CosmosClient. Helpful for tracing using Diagnostic Settings	no
pointRead.partitionKey	string	Partition Key value or parameter to bind.	yes
pointRead.id	string	Document Id value or parameter to bind.	yes
pointRead.parameters	array	Array of parameter to bind in `partitionKey` and `id`	yes if parameters used

Create Options

Attribute	Type	Description	Required
taskCount	integer	Number of concurrent tasks to run	yes
intervalMS	integer	Interval/delay between interations within the same task	yes
applicationName	string	Application name used for CosmosClient. Helpful for tracing using Diagnostic Settings	no
allowBulk	boolean	Flag to use Bulk Mode. Default: false.	no
create.entity	JSON object	Any JSON object to create. Include parameters to bind.	yes
create.partitionKey	array	Specify container partition. Single or multiple (hierarchical partition)	yes
create.parameters	array	Array of parameters to bind in entity	yes

Upsert Options

Attribute	Type	Description	Required
taskCount	integer	Number of concurrent tasks to run	yes
intervalMS	integer	Interval/delay between interations within the same task	yes
applicationName	string	Application name used for CosmosClient. Helpful for tracing using Diagnostic Settings	no
allowBulk	boolean	Flag to use Bulk Mode.. Default: false.	no
upsert.entity	JSON object	Any JSON object to create. Include parameters to bind.	yes
upsert.partitionKey	array	Specify container partition. Single or multiple (hierarchical partition)	yes
upsert.parameters	array	Array of parameters to bind in entity	yes

Parameter Options

Attribute	Type	Description	Required
name	string	Parameter name matching the ones used in the test config	yes
type	string	Parameter type. Allowed values: `guid`, `datetime`, `random_int`, `random_int_as_string`, `sequential_int`, `sequential_int_as_string`, `random_list`, `random_bool`, `faker.firstname`, `faker.lastname`, `faker.fullname`, `faker.dateofbirth`, `faker.address`, `faker.phone`, `faker.email`	yes
start	int	Range start for `random_int(_as_string)` or `sequential_int(_as_string)`	yes if `random_int(_as_string)` or `sequential_int(_as_string)`
end	int	Range end for `random_int(_as_string)`	yes if `random_int(_as_string)`
list	array	List of values to be randomly picked	yes if `random_list`

Same parameter can be assigned to multiple entity attributes.

Monitoring

You can use Insights pane or Metrics to monitor your test. Monitor and debug with insights in Azure Cosmos DB
You can use Diagnostic settings for richer analysis. Monitor Azure Cosmos DB data by using diagnostic settings in Azure

Clean Up

CTRL + C to stop load tester
Remember to delete or scale down any provisioned resource.

How to Contribute

If you find any errors or have suggestions for changes, please be part of this project!

Create your branch: git checkout -b my-new-feature
Add your changes: git add .
Commit your changes: git commit -m '<message>'
Push your branch to Github: git push origin my-new-feature
Create a new Pull Request 😄

fonsecamar/cosmos-loadtest