您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

监视 Azure Cosmos DBMonitor Azure Cosmos DB

适用于: SQL API Cassandra API Gremlin API 表 API Azure Cosmos DB API for MongoDB

当你的关键应用程序和业务流程依赖于 Azure 资源时,你需要监视这些资源的可用性、性能和操作。When you have critical applications and business processes relying on Azure resources, you want to monitor those resources for their availability, performance, and operation. 本文介绍 Azure Cosmos 数据库生成的监视数据,以及如何使用 Azure Monitor 的功能在此数据的基础上进行分析和发出警报。This article describes the monitoring data generated by Azure Cosmos databases and how you can use the features of Azure Monitor to analyze and alert on this data.

可以通过客户端和服务器端指标监视数据。You can monitor your data with client-side and server-side metrics. 使用服务器端指标时,可以使用以下选项监视存储在 Azure Cosmos DB 中的数据:When using server-side metrics, you can monitor the data stored in Azure Cosmos DB with the following options:

  • 通过 Azure Cosmos DB 门户监视: 可以使用 Azure Cosmos 帐户的“指标”选项卡中提供的指标进行监视。Monitor from Azure Cosmos DB portal: You can monitor with the metrics available within the Metrics tab of the Azure Cosmos account. 此选项卡上的指标包括吞吐量、存储、可用性、延迟、一致性和系统级指标。The metrics on this tab include throughput, storage, availability, latency, consistency, and system level metrics. 默认情况下,这些指标的保留期为 7 天。By default, these metrics have a retention period of 7 days. 若要了解详细信息,请参阅本文的从 Azure Cosmos DB 中收集的监视数据部分。To learn more, see the Monitoring data collected from Azure Cosmos DB section of this article.

  • 使用 Azure Monitor 中的指标进行监视: 可以监视 Azure Cosmos 帐户的指标,并从 Azure Monitor 中创建仪表板。Monitor with metrics in Azure monitor: You can monitor the metrics of your Azure Cosmos account and create dashboards from the Azure Monitor. 默认情况下,Azure Monitor 收集 Azure Cosmos DB 指标,你无需显式配置任何内容。Azure Monitor collects the Azure Cosmos DB metrics by default, you don’t have configure anything explicitly. 这些指标以一分钟的粒度进行收集,粒度可能因所选指标而异。These metrics are collected with one-minute granularity, the granularity may vary based on the metric you choose. 默认情况下,这些指标的保留期为 30 天。By default, these metrics have a retention period of 30 days. 从前面选项中获得的大多数指标也可在这些指标中使用。Most of the metrics that are available from the previous options are also available in these metrics. 指标的维度值(例如容器名称)不区分大小写。The dimension values for the metrics such as container name are case-insensitive. 因此,在对这些维度值进行字符串比较时,需要使用不区分大小写的比较。So you need to use case-insensitive comparison when doing string comparisons on these dimension values. 若要了解详细信息,请参阅本文的分析指标数据部分。To learn more, see the Analyze metric data section of this article.

  • 使用 Azure Monitor 中的诊断日志进行监视: 可以监视 Azure Cosmos 帐户的日志,并从 Azure Monitor 中创建仪表板。Monitor with diagnostic logs in Azure Monitor: You can monitor the logs of your Azure Cosmos account and create dashboards from the Azure Monitor. 以秒粒度发生的遥测(例如,事件和跟踪)将作为日志进行存储。Telemetry such as events and traces that occur at a second granularity are stored as logs. 例如,如果容器的吞吐量发生变化,则 Cosmos 帐户的属性也会发生变化,这些事件将在日志中捕获。For example, if the throughput of a container is changes, the properties of a Cosmos account are changed these events are captures within the logs. 可以通过对收集的数据运行查询来分析这些日志。You can analyze these logs by running queries on the gathered data. 若要了解详细信息,请参阅本文的分析日志数据部分。To learn more, see the Analyze log data section of this article.

  • 使用 SDK 以编程方式监视: 可以使用 .NET、Java、Python、Node.js SDK 和 REST API 中的标头以编程方式监视 Azure Cosmos 帐户。Monitor programmatically with SDKs: You can monitor your Azure Cosmos account programmatically by using the .NET, Java, Python, Node.js SDKs, and the headers in REST API. 若要了解详细信息,请参阅本文的以编程方式监视 Azure Cosmos DB 部分。To learn more, see the Monitoring Azure Cosmos DB programmatically section of this article.

下图显示了可用于通过 Azure 门户监视 Azure Cosmos DB 帐户的不同选项:The following image shows different options available to monitor Azure Cosmos DB account through Azure portal:

Azure 门户中提供的监视选项

使用 Azure Cosmos DB 时,可以在客户端上收集有关请求费用、活动 ID、异常/堆栈跟踪信息、HTTP 状态/子状态代码、诊断字符串的详细信息,以调试可能发生的任何问题。When using Azure Cosmos DB, at the client-side you can collect the details for request charge, activity ID, exception/stack trace information, HTTP status/sub-status code, diagnostic string to debug any issue that might occur. 如果需要与 Azure Cosmos DB 支持团队联系,也需要这些信息。This information is also required if you need to reach out to the Azure Cosmos DB support team.

Monitor 概述Monitor overview

Azure 门户中每个 Azure Cosmos DB 帐户的“概述”页面包含资源使用情况的简要视图,例如请求总数、导致特定 HTTP 状态代码的请求,以及每小时计费。The Overview page in the Azure portal for each Azure Cosmos DB account includes a brief view of the resource usage, such as total requests, requests that resulted in a specific HTTP status code, and hourly billing. 这些信息非常有用,但此页面只提供少量的监视数据。This information is helpful, however only a small amount of the monitoring data is available from this pane. 创建资源后,其中的某些数据会自动收集,并可供分析。Some of this data is collected automatically and is available for analysis as soon as you create the resource. 你可以使用某些配置启用其他数据收集类型。You can enable additional types of data collection with some configuration.

说明是 Azure Monitor?What is Azure Monitor?

Azure Cosmos DB 使用 Azure Monitor 创建监视数据,后者是 Azure 中的一项完整堆栈监视服务,它提供了一组完整的功能来监视 Azure 资源以及其他云中和本地的资源。Azure Cosmos DB creates monitoring data using Azure Monitor which is a full stack monitoring service in Azure that provides a complete set of features to monitor your Azure resources in addition to resources in other clouds and on-premises.

如果你尚不熟悉如何监视 Azure 服务,请从使用 Azure Monitor 监视 Azure 资源一文着手,其中介绍了以下概念:If you're not already familiar with monitoring Azure services, start with the article Monitoring Azure resources with Azure Monitor which describes the following concepts:

  • 说明是 Azure Monitor?What is Azure Monitor?
  • 与监视相关的成本Costs associated with monitoring
  • 监视 Azure 中收集的数据Monitoring data collected in Azure
  • 配置数据收集Configuring data collection
  • Azure 中用于分析监视数据并就其发出警报的标准工具Standard tools in Azure for analyzing and alerting on monitoring data

本文的以下各部分介绍如何从 Azure Cosmos DB 收集特定数据,并提供了有关使用 Azure 工具配置数据收集和分析此数据的示例。The following sections build on this article by describing the specific data gathered from Azure Cosmos DB and providing examples for configuring data collection and analyzing this data with Azure tools.

适用于 Azure Cosmos DB 的 Azure MonitorAzure Monitor for Azure Cosmos DB

适用于 Azure Cosmos DB 的 Azure Monitor 基于 Azure Monitor 的工作簿功能,并使用以下部分中所述的为 Azure Cosmos DB 收集的相同监视数据。Azure Monitor for Azure Cosmos DB is based on the workbooks feature of Azure Monitor and uses the same monitoring data collected for Azure Cosmos DB described in the sections below. 使用 Azure Monitor 以统一的交互式体验查看所有 Azure Cosmos DB 资源的总体性能、故障、容量和操作运行状况,并利用 Azure Monitor 的其他功能进行详细分析和发出警报。Use Azure Monitor for a view of the overall performance, failures, capacity, and operational health of all your Azure Cosmos DB resources in a unified interactive experience, and leverage the other features of Azure Monitor for detailed analysis and alerting. 若要了解详细信息,请参阅文章探究适用于 Azure Cosmos DB 的 Azure MonitorTo learn more, see the Explore Azure Monitor for Azure Cosmos DB article.


创建容器时,请确保不创建名称相同但大小写不同的两个容器。When creating containers, make sure you don’t create two containers with the same name but different casing. 这是因为 Azure 平台的某些部分不区分大小写,这可能会对具有此类名称的容器导致遥测和操作混乱/冲突。That’s because some parts of the Azure platform are not case-sensitive, and this can result in confusion/collision of telemetry and actions on containers with such names.

监视数据Monitoring data

Azure Cosmos DB 会收集与来自 Azure 资源的监视数据中所述的其他 Azure 资源相同类型的监视数据。Azure Cosmos DB collects the same kinds of monitoring data as other Azure resources which are described in Monitoring data from Azure resources. 有关 Azure Cosmos DB 创建的日志和指标的详细参考,请参阅 Azure Cosmos DB 监视数据参考See Azure Cosmos DB monitoring data reference for a detailed reference of the logs and metrics created by Azure Cosmos DB.

Azure 门户中每个 Azure Cosmos 数据库的“概述”页都提供数据库使用情况的简要视图,其中包括该数据库的请求和每小时计费。The Overview page in the Azure portal for each Azure Cosmos database includes a brief view of the database usage including its request and hourly billing usage. 这些信息非常有用,但只提供少量监视数据。This is useful information but only a small amount of the monitoring data available. 创建数据库后,系统会立即自动收集上述某些数据并使其可用于分析;同时,你可以使用某项配置启用其他数据收集。Some of this data is collected automatically and available for analysis as soon as you create the database while you can enable additional data collection with some configuration.


收集和路由Collection and routing

平台指标和活动日志会自动收集和存储,但你可以使用诊断设置将其路由到其他位置。Platform metrics and the Activity log are collected and stored automatically, but can be routed to other locations by using a diagnostic setting.

在创建诊断设置并将其路由到一个或多个位置之前,不会收集和存储资源日志。Resource Logs are not collected and stored until you create a diagnostic setting and route them to one or more locations.

若要了解使用 Azure 门户创建诊断设置的详细过程以及一些诊断查询示例,请参阅创建诊断设置以收集 Azure 中的平台日志和指标See Create diagnostic setting to collect platform logs and metrics in Azure for the detailed process for creating a diagnostic setting using the Azure portal and some diagnostic query examples. 创建诊断设置时,请指定要收集的日志类别。When you create a diagnostic setting, you specify which categories of logs to collect.

以下部分将讨论可以收集的指标和日志。The metrics and logs you can collect are discussed in the following sections.

分析指标Analyzing metrics

Azure Cosmos DB 提供了一个自定义体验来用于处理指标。Azure Cosmos DB provides a custom experience for working with metrics. 可以从“Azure Monitor”菜单中打开“指标”,使用指标资源管理器根据来自其他 Azure 服务的指标分析 Azure Cosmos DB 的指标 。You can analyze metrics for Azure Cosmos DB with metrics from other Azure services using Metrics explorer by opening Metrics from the Azure Monitor menu. 有关使用此工具的详细信息,请参阅 Azure 指标资源管理器入门See Getting started with Azure Metrics Explorer for details on using this tool. 还可以查看如何监视 Azure Cosmos DB 资源的 服务器端延迟请求单位使用情况规范化请求单位使用情况You can also checkout how to monitor server-side latency, request unit usage, and normalized request unit usage for your Azure Cosmos DB resources.

有关为 Azure Cosmos DB 收集的平台指标的列表,请参阅监视 Azure Cosmos DB 数据参考指标一文。For a list of the platform metrics collected for Azure Cosmos DB, see Monitoring Azure Cosmos DB data reference metrics article.

Azure Cosmos DB 的所有指标都位于命名空间“Cosmos DB 标准指标”中。All metrics for Azure Cosmos DB are in the namespace Cosmos DB standard metrics. 在将筛选器添加到图表时,可对这些指标使用以下维度:You can use the following dimensions with these metrics when adding a filter to a chart:

  • CollectionNameCollectionName
  • DatabaseNameDatabaseName
  • OperationTypeOperationType
  • 区域Region
  • StatusCodeStatusCode

若要参考,可以查看 Azure Monitor 中所有受支持的资源指标列表。For reference, you can see a list of all resource metrics supported in Azure Monitor.

查看 Azure Cosmos DB 的操作级别指标View operation level metrics for Azure Cosmos DB

  1. 登录 Azure 门户Sign in to the Azure portal.

  2. 在左侧导航栏中选择“监视”,然后选择“指标”。 Select Monitor from the left-hand navigation bar, and select Metrics.

    Azure Monitor 中的“指标”窗格

  3. 在“指标”窗格中选择一个资源,然后选择所需的订阅和资源组。 From the Metrics pane > Select a resource > choose the required subscription, and resource group. 对于“资源类型”,请选择“Azure Cosmos DB 帐户”,选择一个现有的 Azure Cosmos 帐户,然后选择“应用”。 For the Resource type, select Azure Cosmos DB accounts, choose one of your existing Azure Cosmos accounts, and select Apply.

    选择 Cosmos DB 帐户以查看指标

  4. 接下来,可以从可用指标列表中选择一个指标。Next you can select a metric from the list of available metrics. 可以选择特定于请求单位、存储、延迟、可用性、Cassandra 和其他方面的指标。You can select metrics specific to request units, storage, latency, availability, Cassandra, and others. 若要详细了解此列表中的所有可用指标,请参阅按类别划分的指标一文。To learn in detail about all the available metrics in this list, see the Metrics by category article. 在此示例中,让我们选择“请求单位”和“平均”作为聚合值。In this example, let's select Request units and Avg as the aggregation value.

    除这些详细信息外,还可以选择指标的“时间范围”和“时间粒度”。 In addition to these details, you can also select the Time range and Time granularity of the metrics. 可以查看过去最长 30 天的指标。At max, you can view metrics for the past 30 days. 应用筛选器后,系统会根据该筛选器显示图表。After you apply the filter, a chart is displayed based on your filter. 可以查看所选时间段内每分钟消耗的平均请求单位数。You can see the average number of request units consumed per minute for the selected period.

    从 Azure 门户中选择指标

向指标添加筛选器Add filters to metrics

还可以按 CollectionNameDatabaseNameOperationTypeRegionStatusCode 筛选指标及显示的图表。You can also filter metrics and the chart displayed by a specific CollectionName, DatabaseName, OperationType, Region, and StatusCode. 若要筛选指标,请选择“添加筛选器”,选择所需的属性(例如 OperationType),然后选择一个值(例如 Query)。To filter the metrics, select Add filter and choose the required property such as OperationType and select a value such as Query. 然后,图表中会显示查询操作在所选时间段内消耗的请求单位数。The graph then displays the request units consumed for the query operation for the selected period. 不会记录通过存储过程执行的操作,因此 OperationType 指标下不会显示这些操作。The operations executed via Stored procedure are not logged so they are not available under the OperationType metric.


可以使用“应用拆分”选项将指标分组。You can group metrics by using the Apply splitting option. 例如,可按操作类型将请求单位分组,并一次性查看所有操作的图表,如下图所示:For example, you can group the request units per operation type and view the graph for all the operations at once as shown in the following image:


分析日志Analyzing logs

Azure Monitor 日志中的数据以表形式存储,每个表包含自己独有的属性集。Data in Azure Monitor Logs is stored in tables which each table having its own set of unique properties.

Azure Monitor 中的所有资源日志都具有后跟服务特定字段的相同字段。All resource logs in Azure Monitor have the same fields followed by service-specific fields. Azure Monitor 资源日志架构概述了常见架构。The common schema is outlined in Azure Monitor resource log schema. 有关为 Azure Cosmos DB 收集的资源日志类型的列表,请参阅监视 Azure Cosmos DB 数据参考For a list of the types of resource logs collected for Azure Cosmos DB, see Monitoring Azure Cosmos DB data reference.

活动日志是 Azure 中的一种平台日志,可用于深入了解订阅级别事件。The Activity log is a platform login Azure that provides insight into subscription-level events. 你可以单独查看它或将它路由到 Azure Monitor 日志,然后便可以在其中使用 Log Analytics 执行复杂得多的查询。You can view it independently or route it to Azure Monitor Logs, where you can do much more complex queries using Log Analytics.

Azure Cosmos DB 将数据存储在以下表中。Azure Cosmos DB stores data in the following tables.

Table 说明Description
AzureDiagnosticsAzureDiagnostics 由多个服务用来存储资源日志的公用表。Common table used by multiple services to store Resource logs. 可以使用 MICROSOFT.DOCUMENTDB 识别来自 Azure Cosmos DB 的资源日志。Resource logs from Azure Cosmos DB can be identified with MICROSOFT.DOCUMENTDB.
AzureActivityAzureActivity 用于存储活动日志中所有记录的公用表。Common table that stores all records from the Activity log.

示例 Kusto 查询Sample Kusto queries


从 Azure Cosmos DB 菜单中选择“日志”时,Log Analytics 随即打开,其查询范围设置为当前 Azure Cosmos DB 帐户。When you select Logs from the Azure Cosmos DB menu, Log Analytics is opened with the query scope set to the current Azure Cosmos DB account. 这意味着日志查询只包含来自该资源的数据。This means that log queries will only include data from that resource. 如果你希望运行的查询包含来自其他帐户或其他 Azure 服务的数据,请从“Azure Monitor”菜单中选择“日志”。If you want to run a query that includes data from other accounts or data from other Azure services, select Logs from the Azure Monitor menu. 有关详细信息,请参阅 Azure Monitor Log Analytics 中的日志查询范围和时间范围See Log query scope and time range in Azure Monitor Log Analytics for details.

可在“日志搜索”搜索栏中输入下面这些查询,以便监视 Azure Cosmos 资源。Here are some queries that you can enter into the Log search search bar to help you monitor your Azure Cosmos resources. 这些查询使用新语言These queries work with the new language.

  • 若要查询指定时间段内来自 Azure Cosmos DB 的所有诊断日志,请执行以下操作:To query for all of the diagnostic logs from Azure Cosmos DB for a specified time period:

    | where ResourceProvider=="Microsoft.DocumentDb" and Category=="DataPlaneRequests"
  • 查询已按资源分组的所有操作:To query for all operations, grouped by resource:

    | where ResourceProvider=="Microsoft.DocumentDb" and Category=="DataPlaneRequests" 
    | summarize count() by Resource
  • 查询已按资源分组的所有用户活动:To query for all user activity, grouped by resource:

    | where Caller == "test@company.com" and ResourceProvider=="Microsoft.DocumentDb" and Category=="DataPlaneRequests" 
    | summarize count() by Resource


在监视数据中发现重要情况时,Azure Monitor 警报会主动通知你。Azure Monitor alerts proactively notify you when important conditions are found in your monitoring data. 有了警报,你就可以在客户注意到你的系统中的问题之前确定和解决它们。They allow you to identify and address issues in your system before your customers notice them. 可以在指标日志活动日志上设置警报。You can set alerts on metrics, logs, and the activity log. 不同类型的警报各有优缺点Different types of alerts have benefits and drawbacks

例如,下表列出了资源的几个警报规则。For example, the following table lists few alert rules for your resources. 可以从 Azure 门户中找到警报规则的详细列表。You can find a detailed list of alert rules from the Azure portal. 若要了解详细信息,请参阅如何配置警报一文。To learn more, see how to configure alerts article.

警报类型Alert type 条件Condition 描述Description
请求单位的速率限制(指标警报)Rate limiting on request units (metric alert) 维度名称:StatusCode,运算符:等于,维度值:429Dimension name: StatusCode, Operator: Equals, Dimension values: 429 如果容器或数据库已超出预配的吞吐量限制,则会发出警报。Alerts if the container or a database has exceeded the provisioned throughput limit.
已故障转移区域Region failed over 运算符:大于,聚合类型:计数,阈值:1Operator: Greater than, Aggregation type: Count, Threshold value: 1 单个区域发生故障转移时。When a single region is failed over. 如果未启用自动故障转移,则此警报非常有用。This alert is helpful if you didn't enable automatic failover.
轮换密钥(活动日志警报)Rotate keys(activity log alert) 事件级别:信息,状态:已启动Event level: Informational , Status: started 当轮换帐户密钥时发出警报。Alerts when the account keys are rotated. 你可以用新密钥更新你的应用程序。You can update your application with the new keys.

以编程方式监视 Azure Cosmos DBMonitor Azure Cosmos DB programmatically

门户中可用的帐户级别指标(如帐户存储使用情况和请求总数)不可通过 SQL API 使用。The account level metrics available in the portal, such as account storage usage and total requests, are not available via the SQL APIs. 但是,可以使用 SQL API 在集合级别检索使用情况数据。However, you can retrieve usage data at the collection level by using the SQL APIs. 若要检索集合级别的数据,请执行以下操作:To retrieve collection level data, do the following:

若要访问其他指标,请使用 Azure Monitor SDKTo access additional metrics, use the Azure Monitor SDK. 可以通过调用以下命令检索可用的指标定义:Available metric definitions can be retrieved by calling:


若要检索单个指标,请使用以下格式:To retrieve individual metrics use the following format:


若要了解详细信息,请参阅 Azure 监视 REST API 一文。To learn more, see the Azure monitoring REST API article.

后续步骤Next steps