Monitoring Azure CosmosDB

Note: Learn about the other supported Azure services with our Azure documentation.

Azure Cosmos DB is Microsoft's globally distributed, multi-model database service. Instana supports monitoring per collection metrics and depending on the used model, we also support the monitoring of model specific metrics per collection.

Data is organized in a drill-down fashion with 4 levels of metrics. At the top, you can see aggregated instance metrics. These metrics apply to the whole CosmosDb instance.

Next level is per-region metrics. Region metrics are aggregated over all collections that exist inside that region, but it also contains inter-region traffic and other traffic. This means that the numbers you will see per region will be a bit higher than the sum of traffic in all collections in that region.

The third level becomes visible once you expand a region. Here you can see per collection metrics. Based on the data model, each collection will have additional metrics that you can see by expanding the collection view.

The frequency we collect metrics is dictated by Azure Monitor SDK.

Configuration

Azure CosmosDB sensor can be disabled and it can be filtered by tags and resource groups. It is possible to configure Azure CosmosDB sensor via agent configuration in <agentinstall_dir>/etc/instana/configuration.yaml by:

com.instana.plugin.azure.cosmosdb:
  # Valid values: true, false
  enabled: false # enabled (true) by default
  # Comma separated list of tags in key:value format
  include_tags:
  # Comma separated list of tags in key:value format
  exclude_tags:
  # Comma separated list of resource groups
  include_resource_groups:
  # Comma separated list of resource groups
  exclude_resource_groups:

Azure CosmosDB sensor can be disabled. To disable monitoring of the Azure CosmosDB services use the following configuration:

com.instana.plugin.azure.cosmosdb:
  enabled: false

Multiple tags and resource groups can be defined, separated by a comma. Tags should be provided as a key-value pair separated by :. In order to make configuration easier, it is possible to define which tags and resource groups you want to include in discovery or exclude from discovery. In case of defining tag or resource group in both lists (include and exclude), exclude list has higher priority. If there is no need for services filtering, the configuration should not be defined. It's not mandatory to define all values in order to enable filtering.

To include services by tags into discovery use following configuration:

com.instana.plugin.azure.cosmosdb:
  include_tags: # Comma separated list of tags in key:value format (e.g. env:prod,env:staging)

To exclude services by tags from discovery use following configuration:

com.instana.plugin.azure.cosmosdb:
  exclude_tags: # Comma separated list of tags in key:value format (e.g. env:dev,env:test)

To include services by resource groups into discovery use following configuration:

com.instana.plugin.azure.cosmosdb:
  include_resource_groups: # Comma separated list of resource groups (e.g. rg_prod,rg_staging)

To exclude services by resource groups from discovery use following configuration:

com.instana.plugin.azure.cosmosdb:
  exclude_resource_groups: # Comma separated list of resource groups (e.g. rg_dev,rg_test)

Discovery filtering can be configured on the global level for all Azure services. In case of defining filters for Azure CosmosDB service, global filters will be overridden. For more details about global Azure service discovery filtering visit Azure Configuration.

Metrics collection

Configuration data

List of static information per CosmosDB instance.

CosmosDB Details Description
Name The name of the CosmosDB instance.
Resource Group The resource group of the CosmosDB instance.
Location The main region where the instance is located
Subscription Id The subscription ID of the CosmosDB instance.
State Current deployment state of the instance.
API Document model type (GlobalDB, Cassandra or MongoDB)
Type Document type
Kind Indicates the type of database account
Endpoint Database endpoint

Summary

The first level of metrics aggregated for the whole CosmosDB instance.

CosmosDB Instance Metric Description Granularity
Document Count Number of documents that exist in the whole instance 5 minutes
Service Availability Expressed in % 1 hour
Total Requests Total number of all requests 1 minute
Metadata Requests Total number of metadata requests 1 minute
Read Latency 1 minute
Write Latency 1 minute

Regions

Per-region metrics contain aggregated data for all collections in that region plus metrics that happen on region levels like inter-region metrics or metadata requests.

Region Metrics Granularity
Total Requests 1 minute
Metadata Requests 1 minute
Document Count 5 minute

Collections

Each region has one or more collections. Each collection has a set of metrics that will be available regardless of the document model:

Collection Metrics Description Granularity
Total Requests Number of total requests 1 minute
Metadata Requests Number of metadata requests 1 minute
Document Count Number of documents stored in this collection 5 minutes
Data Usage Number of bytes used to store all documents 5 minutes
Index Usage Total amount of storage available 5 minutes
Document Quota Total amount of storage available for storing documents 5 minutes
Status codes Metrics of total requests per status code 1 minute

Based on the document model (API) there are some additional metrics that we collect:

Cassandra

Collection Metrics Description Granularity
Resource type Requests per resource type 1 minute

Mongo DB

Collection Metrics Description Granularity
Command type Requests per command type 1 minute
Error code Requests per error code 1 minute

Health signatures

For each sensor, there is a curated knowledgebase of health signatures that are evaluated continuously against the incoming metrics and are used to raise issues or incidents depending on user impact.

Built-in events trigger issues or incidents based on failing health signatures on entities, and custom events trigger issues or incidents based on the thresholds of an individual metric of any given entity.

For information about built-events for Azure CosmosDB sensor, see the Built-in events reference.