Retrieve and use query metrics

When designing and implementing native applications using Microsoft Azure Cosmos DB, it is important to retrieve and use query metrics to monitor and optimize the performance of your queries. Query metrics provide valuable insights into query execution, resource utilization, and request units (RUs) consumption. By leveraging the built-in monitoring capabilities of Cosmos DB, you can improve the efficiency and overall user experience of your applications.

1. Enable Metrics Collection

Before you can retrieve query metrics, it is necessary to enable metrics collection on your Cosmos DB account. This can be done either through the Azure portal or programmatically using Azure PowerShell or Azure CLI.

2. QueryExecutionTimeInMs Metric

The QueryExecutionTimeInMs metric provides information about the time taken to execute queries. To retrieve this metric for a specific query, you can query the Cosmos DB metric API using the MetricDefinitions and Metrics endpoints. Below is an example code snippet in C#:

csharp
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.Cosmos.Scripts;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
static async Task Main(string[] args)
{
string endpointUri = “your-cosmosdb-endpoint”;
string primaryKey = “your-cosmosdb-primary-key”;
string databaseName = “your-database-name”;
string containerName = “your-container-name”;

using (CosmosClient cosmosClient = new CosmosClient(endpointUri, primaryKey))
{
Database database = cosmosClient.GetDatabase(databaseName);
Container container = database.GetContainer(containerName);

string queryText = “SELECT * FROM c”;
QueryDefinition queryDefinition = new QueryDefinition(queryText);

FeedIterator queryResultSetIterator = container.GetItemQueryIterator(
queryDefinition,
requestOptions: new QueryRequestOptions
{
EnableQueryMetrics = true // Enable query metrics
});

while (queryResultSetIterator.HasMoreResults)
{
FeedResponse currentResultSet = await queryResultSetIterator.ReadNextAsync();
Console.WriteLine($”QueryMetrics: {currentResultSet.QueryMetrics}”);
}
}
}
}

This code snippet demonstrates how to execute a query and retrieve the query metrics using the Cosmos DB .NET SDK. By setting the EnableQueryMetrics property to true in the QueryRequestOptions, you enable metrics collection. The query metrics can then be accessed through the QueryMetrics property of the FeedResponse object.

3. Request Units (RUs) Consumption

Azure Cosmos DB measures query throughput using Request Units (RUs), which represent the cost of executing a query in terms of resource utilization. You can retrieve the RU consumption for a query using the TotalRequestCharge property of the FeedResponse object obtained from querying Cosmos DB.

Here’s an example of retrieving the RU consumption using JavaScript in a browser environment:

javascript
const endpoint = “your-cosmosdb-endpoint”;
const key = “your-cosmosdb-primary-key”;
const databaseName = “your-database-name”;
const containerName = “your-container-name”;

const client = new CosmosClient({ endpoint, key });
const container = client.database(databaseName).container(containerName);

const query = “SELECT * FROM c”;

const { resources, queryMetrics } = await container.items
.query(query, { enableCrossPartitionQuery: true, populateQueryMetrics: true })
.fetchAll();

console.log(`QueryMetrics: ${JSON.stringify(queryMetrics)}`);
console.log(`RU Consumption: ${resources.requestCharge}`);

This JavaScript code demonstrates querying Cosmos DB using the JavaScript SDK. The fetchAll() method executes the query and retrieves the query metrics and RU consumption. By setting the populateQueryMetrics option to true, you enable metrics collection.

By retrieving and analyzing query metrics and RU consumption, you can gain insights into query performance, identify bottlenecks, and optimize your application to achieve optimal efficiency. Remember to modify the code snippets with your actual Cosmos DB endpoint, keys, database name, and container name. Additionally, ensure that you have the relevant SDKs or libraries installed based on your programming language or environment.

By utilizing query metrics in your native applications built with Microsoft Azure Cosmos DB, you can effectively monitor and optimize query performance, resulting in improved efficiency and enhanced user experience.