Azure Cosmos DB 中的诊断日志记录Diagnostic logging in Azure Cosmos DB

开始使用一个或多个 Azure Cosmos 数据库后,可能需要监视数据库的访问方式和时间。After you start to use one or more Azure Cosmos databases, you may want to monitor how and when your databases are accessed. 本文概述了 Azure 平台上提供的日志。This article provides an overview of the logs that are available on the Azure platform. 其中介绍了如何启用监视用的诊断日志记录,以便将日志发送到 Azure 存储,将日志流式传输到 Azure 事件中心,以及如何将日志导出到 Azure Monitor 日志You learn how to enable diagnostic logging for monitoring purposes to send logs to Azure Storage, how to stream logs to Azure Event Hubs, and how to export logs to Azure Monitor logs.

备注

本文最近已更新,从使用术语“Log Analytics”改为使用术语“Azure Monitor 日志”。This article was recently updated to use the term Azure Monitor logs instead of Log Analytics. 日志数据仍然存储在 Log Analytics 工作区中,并仍然由同一 Log Analytics 服务收集并分析。Log data is still stored in a Log Analytics workspace and is still collected and analyzed by the same Log Analytics service. 我们正在更新术语,以便更好地反映 Azure Monitor 中日志的角色。We are updating the terminology to better reflect the role of logs in Azure Monitor. 有关详细信息,请参阅 Azure Monitor 术语更改See Azure Monitor terminology changes for details.

备注

本文进行了更新,以便使用新的 Azure PowerShell Az 模块。This article has been updated to use the new Azure PowerShell Az module. 你仍然可以使用 AzureRM 模块,至少在 2020 年 12 月之前,它将继续接收 bug 修补程序。You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 若要详细了解新的 Az 模块和 AzureRM 兼容性,请参阅新 Azure Powershell Az 模块简介To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. 有关 Az 模块安装说明,请参阅安装 Azure PowerShellFor Az module installation instructions, see Install Azure PowerShell.

在 Azure 中可用的日志Logs available in Azure

在探讨如何监视 Azure Cosmos DB 帐户之前,让我们先澄清一些有关日志记录和监视的事项。Before we talk about how to monitor your Azure Cosmos DB account, let's clarify a few things about logging and monitoring. Azure 平台上有不同类型的日志。There are different types of logs on the Azure platform. Azure 活动日志Azure 诊断日志Azure 指标日志、事件日志、检测信号监视日志、操作日志,等等。There are Azure Activity Logs, Azure Diagnostic Logs, Azure metrics, events, heartbeat monitoring, operations logs, and so on. 有很多种日志。There is a plethora of logs. 可以在 Azure 门户的 Azure Monitor 日志中看到日志的完整列表。You can see the complete list of logs in Azure Monitor logs in the Azure portal.

下图显示所提供的不同种类的 Azure 日志:The following image shows the different kind of Azure logs that are available:

不同种类的 Azure 日志

在上图中,计算资源表示可以访问其 Azure 来宾 OS 的 Azure 资源。In the image, the Compute resources represent the Azure resources for which you can access the Azure Guest OS. 例如,Azure 虚拟机、虚拟机规模集、Azure 容器服务等都视为计算资源。For example, Azure Virtual Machines, virtual machine scale sets, Azure Container Service, and so on, are considered compute resources. 计算资源生成活动日志、诊断日志和应用程序日志。Compute resources generate Activity Logs, Diagnostic Logs, and Application Logs. 若要了解详细信息,请参阅 Azure 中的监视数据源一文。To learn more, refer to the Sources of monitoring data in Azure article.

“非计算资源”是在其中无法访问基础 OS,但可直接使用资源的资源 。The Non-Compute resources are resources in which you can't access the underlying OS and work directly with the resource. 例如网络安全组、逻辑应用等。For example, Network Security Groups, Logic Apps, and so on. Azure Cosmos DB 是一种非计算资源。Azure Cosmos DB is a non-compute resource. 可以在活动日志中或通过在门户中启用“诊断日志”选项查看非计算资源的日志。You can view logs for non-compute resources in the Activity Log or enable the Diagnostic Logs option in the portal. 若要了解详细信息,请参阅 Azure Monitor 中的数据源一文。To learn more, refer to the Sources of data in Azure Monitor article.

活动日志记录 Azure Cosmos DB 订阅级别的操作。The Activity Log records the operations at a subscription level for Azure Cosmos DB. 将记录 ListKeys、Write DatabaseAccounts 等操作。Operations like ListKeys, Write DatabaseAccounts, and more are logged. 诊断日志提供更精细的日志记录并允许记录 DataPlaneRequests(创建、读取、查询等)和 MongoRequests。Diagnostic Logs provide more granular logging and allow you to log DataPlaneRequests (Create, Read, Query, and so on) and MongoRequests.

本文重点讨论 Azure 活动日志、Azure 诊断日志和 Azure 指标。In this article, we focus on the Azure Activity Log, Azure Diagnostic Logs, and Azure metrics. 这三类日志有何差异?What's the difference between these three logs?

Azure 活动日志Azure Activity Log

Azure 活动日志是一种方便用户深入了解 Azure 中发生的订阅级别事件的订阅日志。The Azure Activity Log is a subscription log that provides insight into subscription-level events that have occurred in Azure. 活动日志在“管理”类别下报告订阅的控制平面事件。The Activity Log reports control-plane events for your subscriptions under the Administrative category. 通过活动日志,可确定订阅中资源上进行的任何写入操作 (PUT, POST, DELETE) 的“什么操作、谁操作和操作时间”等信息。You can use the Activity Log to determine the "what, who, and when" for any write operation (PUT, POST, DELETE) on the resources in your subscription. 还可以了解该操作和其他相关属性的状态。You can also understand the status of the operation and other relevant properties.

活动日志不同于诊断日志。The Activity Log differs from Diagnostic Logs. 活动日志提供有关从外部(“控制面”)对资源所执行操作的数据。 The Activity Log provides data about the operations on a resource from the outside (the control plane). 在 Azure Cosmos DB 上下文中,控制平面操作包括创建容器、列出密钥、删除密钥、列出数据库,等等。In the Azure Cosmos DB context, control plane operations include create container, list keys, delete keys, list database, and so on. 诊断日志由资源发出,并提供有关该资源(“数据平面”)的操作信息。 Diagnostics Logs are emitted by a resource and provide information about the operation of that resource (the data plane). 诊断日志中部分数据平面操作的示例包括 Delete、Insert 和 ReadFeed。Some examples of the data plane operations in the diagnostic log are Delete, Insert, and ReadFeed.

活动日志(控制平面操作)在本质上可能要丰富得多,可能包括:调用方的完整电子邮件地址、调用方 IP 地址、资源名称、操作名称、TenantId,等等。Activity Logs (control plane operations) can be richer in nature and can include the full email address of the caller, caller IP address, resource name, operation name, TenantId, and more. 活动日志包含多个数据类别The Activity Log contains several categories of data. 有关这些类别的架构的完整详细信息,请参阅 Azure 活动日志事件架构For full details on the schemata of these categories, see Azure Activity Log event schema. 但是,诊断日志在本质上可能是限制性的,因为通常会将个人数据从这些日志中剥离出来。However, Diagnostic Logs can be restrictive in nature as personal data is often stripped from these logs. 因此,你可能有调用方的 IP 地址,但最后的八进制数已删除。You might have the IP address of the caller, but the last octant is removed.

Azure 指标Azure metrics

Azure 指标,包含最重要的 Azure 遥测数据类型(也称为“性能计数器”),是大多数 Azure 资源发出的。 Azure metrics have the most important type of Azure telemetry data (also called performance counters) that's emitted by most Azure resources. 可以通过指标来查看与吞吐量、存储、一致性、可用性以及 Azure Cosmos DB 资源的延迟相关的信息。Metrics let you view information about throughput, storage, consistency, availability, and the latency of your Azure Cosmos DB resources. 有关详细信息,请参阅使用 Azure Cosmos DB 中的指标进行监视和调试For more information, see Monitoring and debugging with metrics in Azure Cosmos DB.

Azure 诊断日志Azure Diagnostic Logs

Azure 诊断日志由资源发出,提供与该资源的操作相关的各种频繁生成的数据。Azure Diagnostic Logs are emitted by a resource and provide rich, frequent data about the operation of that resource. 这些日志是按请求捕获的。These logs are captured per request. 这些日志的内容因资源类型而异。The content of these logs varies by resource type. 资源级诊断日志与来宾 OS 级诊断日志也不相同。Resource-level diagnostic logs also differ from Guest OS-level diagnostic logs. 来宾 OS 级诊断日志由在虚拟机内部或其他受支持的资源类型中运行的代理收集。Guest OS diagnostic logs are collected by an agent that's running inside a virtual machine or other supported resource type. 资源级诊断日志不需要代理并从 Azure 平台本身捕获特定于资源的数据。Resource-level diagnostic logs require no agent and capture resource-specific data from the Azure platform itself. 来宾 OS 级诊断日志从操作系统和在虚拟机上运行的应用程序捕获数据。Guest OS-level diagnostic logs capture data from the operating system and applications that are running on a virtual machine.

存储、事件中心或 Azure Monitor 日志的诊断日志记录

Azure 诊断日志记录哪些内容?What is logged by Azure Diagnostic Logs?

  • 记录所有 API 中所有已经过身份验证的后端请求 (TCP/REST),包括由于访问权限、系统错误或错误请求而发生的失败请求。All authenticated backend requests (TCP/REST) across all APIs are logged, including failed requests as a result of access permissions, system errors, or bad requests. 目前不支持用户启动的图形、Cassandra 和表 API 请求。Support for user-initiated Graph, Cassandra, and Table API requests aren't currently available.
  • 对数据库本身的操作,包括对所有文档、容器和数据库的 CRUD 操作。Operations on the database itself, which include CRUD operations on all documents, containers, and databases.
  • 对帐户密钥的操作,包括创建、修改或删除这些密钥。Operations on account keys, which include creating, modifying, or deleting the keys.
  • 导致出现 401 响应的未经身份验证的请求。Unauthenticated requests that result in a 401 response. 例如,请求不包含持有者令牌、格式不正确或已过期,或者包含无效的令牌。For example, requests that don't have a bearer token, or are malformed or expired, or have an invalid token.

在 Azure 门户中启用日志记录Turn on logging in the Azure portal

使用以下步骤在 Azure 门户中启用诊断日志记录:Use the following steps to enable diagnostic logging in the Azure portal:

  1. 登录到 Azure 门户Sign into the Azure portal.

  2. 导航到 Azure Cosmos 帐户。Navigate to your Azure Cosmos account. 打开“诊断设置”窗格,然后选择“添加诊断设置”选项。 Open the Diagnostic settings pane, and then select Add diagnostic setting option.

    在 Azure 门户中启用 Azure Cosmos DB 的诊断日志记录

  3. 在“诊断设置”页的表单中填充以下详细信息: In the Diagnostic settings page, fill the form with the following details:

    • 名称:为要创建的日志输入名称。Name: Enter a name for the logs to create.

    • 可以将日志存储到以下服务:You can store the logs to the following services:

      • 存档到存储帐户:要使用此选项,需要一个可连接到的现有存储帐户。Archive to a storage account: To use this option, you need an existing storage account to connect to. 若要在门户中创建新存储帐户,请参阅创建存储帐户一文。To create a new storage account in the portal, see Create a storage account article. 然后在门户中返回到 Azure Cosmos DB 诊断设置窗格,选择存储帐户。Then, return to the Azure Cosmos Db diagnostic settings pane in the portal to select your storage account. 新创建的存储帐户可能几分钟后才会显示在下拉菜单中。It might take a few minutes for newly created storage accounts to appear in the drop-down menu.

      • 流式传输到事件中心:要使用此选项,需要一个可连接到的现有事件中心命名空间和事件中心。Stream to an event hub: To use this option, you need an existing Event Hubs namespace and event hub to connect to. 要创建事件中心命名空间,请参阅使用 Azure 门户创建事件中心命名空间和事件中心To create an Event Hubs namespace, see Create an Event Hubs namespace and an event hub by using the Azure portal. 然后在门户中返回到此页,选择事件中心命名空间和策略名称。Then, return to this page in the portal to select the Event Hub namespace and policy name.

      • 发送到 Log Analytics:若要使用此选项,请使用现有的工作区,或遵循创建新工作区的步骤在门户中创建新的 Log Analytics 工作区。Send to Log Analytics: To use this option, either use an existing workspace or create a new Log Analytics workspace by following the steps to Create a new workspace in the portal.

    • 可以记录以下数据:You can log the following data:

      • DataPlaneRequests:选择此选项可在 Azure Cosmos DB 中将后端请求记录到所有 API,其中包括 SQL、图形、MongoDB、Cassandra 和表 API 帐户。DataPlaneRequests: Select this option to log back-end requests to all APIs which includes SQL, Graph, MongoDB, Cassandra, and Table API accounts in Azure Cosmos DB. 若要存档到存储帐户,可以选择诊断日志的保留期。If you're archiving to a storage account, you can select the retention period for the diagnostic logs. 保留期到期后自动删除日志。Logs are auto-deleted after the retention period expires. 以下 JSON 数据是使用 DataPlaneRequests 记录的详细信息的示例输出。The following JSON data is an example output of details logged using DataPlaneRequests. 要记录的关键属性:Requestcharge、statusCode、clientIPaddress 和 partitionID:Key properties to note are: Requestcharge, statusCode, clientIPaddress, and partitionID:

        { "time": "2019-04-23T23:12:52.3814846Z", "resourceId": "/SUBSCRIPTIONS/<your_subscription_ID>/RESOURCEGROUPS/<your_resource_group>/PROVIDERS/MICROSOFT.DOCUMENTDB/DATABASEACCOUNTS/<your_database_account>", "category": "DataPlaneRequests", "operationName": "ReadFeed", "properties": {"activityId": "66a0c647-af38-4b8d-a92a-c48a805d6460","requestResourceType": "Database","requestResourceId": "","collectionRid": "","statusCode": "200","duration": "0","userAgent": "Microsoft.Azure.Documents.Common/2.2.0.0","clientIpAddress": "10.0.0.24","requestCharge": "1.000000","requestLength": "0","responseLength": "372","resourceTokenUserRid": "","region": "China East","partitionId": "062abe3e-de63-4aa5-b9de-4a77119c59f8","keyType": "PrimaryReadOnlyMasterKey","databaseName": "","collectionName": ""}}
        
      • MongoRequests:选择此选项可记录用户从前端发起的请求,这些请求的内容是要求处理发送给 Azure Cosmos DB 的 MongoDB API 的请求。MongoRequests: Select this option to log user-initiated requests from the front end to serve requests to Azure Cosmos DB's API for MongoDB. MongoDB 请求会显示在 MongoRequests 和 DataPlaneRequests 中。MongoDB requests will appear in MongoRequests as well as DataPlaneRequests. 若要存档到存储帐户,可以选择诊断日志的保留期。If you're archiving to a storage account, you can select the retention period for the diagnostic logs. 保留期到期后自动删除日志。Logs are auto-deleted after the retention period expires. 以下 JSON 数据是使用 MongoRequests 记录的详细信息的示例输出。The following JSON data is an example output of details logged using MongoRequests. 要记录的关键属性:Requestcharge、opCode:Key properties to note are: Requestcharge, opCode:

        { "time": "2019-04-10T15:10:46.7820998Z", "resourceId": "/SUBSCRIPTIONS/<your_subscription_ID>/RESOURCEGROUPS/<your_resource_group>/PROVIDERS/MICROSOFT.DOCUMENTDB/DATABASEACCOUNTS/<your_database_account>", "category": "MongoRequests", "operationName": "ping", "properties": {"activityId": "823cae64-0000-0000-0000-000000000000","opCode": "MongoOpCode_OP_QUERY","errorCode": "0","duration": "0","requestCharge": "0.000000","databaseName": "admin","collectionName": "$cmd","retryCount": "0"}}
        
      • QueryRuntimeStatistics:选择此选项以记录已执行的查询文本。QueryRuntimeStatistics: Select this option to log the query text that was executed. 以下 JSON 数据是使用 QueryRuntimeStatistics 记录的详细信息的示例输出:The following JSON data is an example output of details logged using QueryRuntimeStatistics:

        { "time": "2019-04-14T19:08:11.6353239Z", "resourceId": "/SUBSCRIPTIONS/<your_subscription_ID>/RESOURCEGROUPS/<your_resource_group>/PROVIDERS/MICROSOFT.DOCUMENTDB/DATABASEACCOUNTS/<your_database_account>", "category": "QueryRuntimeStatistics", "properties": {"activityId": "278b0661-7452-4df3-b992-8aa0864142cf","databasename": "Tasks","collectionname": "Items","partitionkeyrangeid": "0","querytext": "{"query":"SELECT *\nFROM c\nWHERE (c.p1__10 != true)","parameters":[]}"}}
        
      • PartitionKeyStatistics:此日志报告分区键的统计信息。PartitionKeyStatistics: This log reports the statistics of the partition keys. 目前,统计信息用分区键的存储大小 (KB) 来表示。Currently, the statistics is represented with the storage size (KB) of the partition keys. 日志针对占用大部分数据存储空间的前三个分区键发出。The log is emitted against the first three partition keys that occupy most data storage.

        { "time": "2019-10-11T02:33:24.2018744Z", "resourceId": "/SUBSCRIPTIONS/<your_subscription_ID>/RESOURCEGROUPS/<your_resource_group>/PROVIDERS/MICROSOFT.DOCUMENTDB/DATABASEACCOUNTS/<your_database_account>", "category": "PartitionKeyStatistics", "properties": {"subscriptionId": "<your_subscription_ID>","regionName": "China North 2","databaseName": "KustoQueryResults","collectionname": "CapacityMetrics","partitionkey": "["CapacityMetricsPartition.136"]","sizeKb": "2048270"}}
        
      • 指标请求:选择此选项可在 Azure 指标中存储详细数据。Metric Requests: Select this option to store verbose data in Azure metrics. 若要存档到存储帐户,可以选择诊断日志的保留期。If you're archiving to a storage account, you can select the retention period for the diagnostic logs. 保留期到期后自动删除日志。Logs are auto-deleted after the retention period expires.

  4. 选择“保存” 。Select Save.

    如果收到一个错误,指出“无法更新 <工作区名称> 的诊断。If you receive an error that says "Failed to update diagnostics for <workspace name>. 订阅 <订阅 ID> 未注册为使用 microsoft.insights”,请遵照排查 Azure 诊断问题中的说明注册帐户,然后重试此过程。The subscription <subscription id> is not registered to use microsoft.insights," follow the Troubleshoot Azure Diagnostics instructions to register the account and then retry this procedure.

    若要更改在将来的任意时间点保存诊断日志的方式,可以返回到此页,修改帐户的诊断日志设置。If you want to change how your diagnostic logs are saved at any point in the future, return to this page to modify the diagnostic log settings for your account.

使用 Azure CLI 启用日志记录Turn on logging by using Azure CLI

若要使用 Azure CLI 启用指标和诊断日志记录,请使用以下命令:To enable metrics and diagnostics logging by using Azure CLI, use the following commands:

  • 若要允许在存储帐户中存储诊断日志,请使用以下命令:To enable storage of Diagnostic Logs in a storage account, use this command:

    az monitor diagnostic-settings create --name DiagStorage --resource <resourceId> --storage-account <storageAccountName> --logs '[{"category": "QueryRuntimeStatistics", "enabled": true, "retentionPolicy": {"enabled": true, "days": 0}}]'
    

    resource 是 Azure Cosmos DB 帐户的名称。The resource is the name of the Azure Cosmos DB account. 资源采用的格式为“/subscriptions/<subscriptionId>/resourceGroups/<resource_group_name>/providers/Microsoft.DocumentDB/databaseAccounts/<Azure_Cosmos_account_name>” storage-account 是要将日志发送到的存储帐户的名称。The resource is in the format "/subscriptions/<subscriptionId>/resourceGroups/<resource_group_name>/providers/Microsoft.DocumentDB/databaseAccounts/<Azure_Cosmos_account_name>" The storage-account is the name of the storage account to which you want to send the logs. 将类别参数值更新为 "MongoRequests" 或 "DataPlaneRequests" 即可记录其他日志。You can log other logs by updating the category parameter values to "MongoRequests" or "DataPlaneRequests".

  • 要允许将诊断日志流式传输到事件中心,请使用以下命令:To enable streaming of Diagnostic Logs to an event hub, use this command:

    az monitor diagnostic-settings create --name cdbdiagsett --resourceId <resourceId> --event-hub-rule <eventHubRuleID> --logs '[{"category":"QueryRuntimeStatistics","enabled":true,"retentionPolicy":{"days":6,"enabled":true}}]'
    

    resource 是 Azure Cosmos DB 帐户的名称。The resource is the name of the Azure Cosmos DB account. event-hub-rule 是事件中心规则 ID。The event-hub-rule is the event hub rule ID.

  • 若要启用将诊断日志发送到 Log Analytics 工作区,请使用以下命令:To enable sending Diagnostic Logs to a Log Analytics workspace, use this command:

    az monitor diagnostic-settings create --name cdbdiagsett --resourceId <resourceId> --workspace <resource id of the log analytics workspace> --logs '[{"category":"QueryRuntimeStatistics","enabled":true,"retentionPolicy":{"days":6,"enabled":true}}]'
    

可以结合这些参数启用多个输出选项。You can combine these parameters to enable multiple output options.

使用 PowerShell 启用日志记录Turn on logging by using PowerShell

若要使用 PowerShell 启用诊断日志记录,需要版本最低为 1.0.1 的 Azure Powershell。To turn on diagnostic logging by using PowerShell, you need Azure Powershell with a minimum version of 1.0.1.

要安装 Azure PowerShell 并将其与 Azure 订阅相关联,请参阅如何安装和配置 Azure PowerShellTo install Azure PowerShell and associate it with your Azure subscription, see How to install and configure Azure PowerShell.

如果已安装 Azure PowerShell,但不知道版本,请在 PowerShell 控制台中键入 (Get-Module azure -ListAvailable).VersionIf you've already installed Azure PowerShell and don't know the version, from the PowerShell console type (Get-Module azure -ListAvailable).Version.

连接到订阅Connect to your subscriptions

启动 Azure PowerShell 会话,并使用以下命令登录用户的 Azure 帐户:Start an Azure PowerShell session and sign in to your Azure account with the following command:

Connect-AzAccount -Environment AzureChinaCloud

在弹出的浏览器窗口中,输入 Azure 帐户用户名和密码。In the pop-up browser window, enter your Azure account user name and password. Azure PowerShell 会获取与此帐户关联的所有订阅,并按默认使用第一个订阅。Azure PowerShell gets all of the subscriptions that are associated with this account, and by default, uses the first one.

如果有多个订阅,可能需要指定用来创建 Azure Key Vault 的特定订阅。If you have more than one subscription, you might have to specify the specific subscription that was used to create your Azure key vault. 若要查看帐户的订阅,请键入以下命令:To see the subscriptions for your account, type the following command:

Get-AzSubscription

若要指定与要记录的 Azure Cosmos DB 帐户关联的订阅,请键入以下命令:Then, to specify the subscription that's associated with the Azure Cosmos DB account that you're logging, type the following command:

Set-AzContext -SubscriptionId <subscription ID>

备注

如果帐户关联了多个订阅,请务必指定要使用的订阅。If you have more than one subscription that's associated with your account, it's important to specify the subscription that you want to use.

有关如何配置 Azure PowerShell 的详细信息,请参阅 如何安装和配置 Azure PowerShellFor more information about how to configure Azure PowerShell, see How to install and configure Azure PowerShell.

为日志创建新的存储帐户Create a new storage account for your logs

尽管可对日志使用现有存储帐户,但在此教程中,我们创建一个专用于 Azure Cosmos DB 日志的新存储帐户。Although you can use an existing storage account for your logs, in this tutorial, we create a new storage account that's dedicated to Azure Cosmos DB logs. 为方便起见,存储帐户详细信息将存储到名为 sa 的变量中。For convenience, we store the storage account details in a variable named sa.

为进一步简化管理,我们在本教程中使用包含 Azure Cosmos 数据库的同一资源组。For additional ease of management, in this tutorial, we use the same resource group as the one that contains the Azure Cosmos database. ContosoResourceGroupcontosocosmosdblogsChina North 参数替换为自己的值(如适用):Substitute your values for the ContosoResourceGroup, contosocosmosdblogs, and China North parameters, as applicable:

$sa = New-AzStorageAccount -ResourceGroupName ContosoResourceGroup `
-Name contosocosmosdblogs -Type Standard_LRS -Location 'China North'

备注

如果决定使用现有的存储帐户,该帐户必须使用与 Azure Cosmos DB 订阅相同的订阅。If you decide to use an existing storage account, the account must use the same subscription as your Azure Cosmos DB subscription. 该帐户还必须使用资源管理器部署模型,而不是经典部署模型。The account must also use the Resource Manager deployment model, rather than the classic deployment model.

识别日志的 Azure Cosmos DB 帐户Identify the Azure Cosmos DB account for your logs

将 Azure Cosmos DB 帐户名称设置为名为 account 的变量,其中 ResourceName 是 Azure Cosmos DB 帐户的名称。Set the Azure Cosmos DB account name to a variable named account, where ResourceName is the name of the Azure Cosmos DB account.

$account = Get-AzResource -ResourceGroupName ContosoResourceGroup `
-ResourceName contosocosmosdb -ResourceType "Microsoft.DocumentDb/databaseAccounts"

启用日志记录Enable logging

若要启用针对 Azure Cosmos DB 的日志记录,请使用 Set-AzDiagnosticSetting cmdlet,同时使用新存储帐户、Azure Cosmos DB 帐户和要为其启用日志的类别的变量。To enable logging for Azure Cosmos DB, use the Set-AzDiagnosticSetting cmdlet with variables for the new storage account, Azure Cosmos DB account, and the category to enable for logging. 运行以下命令,并将 -Enabled 标志设置为 $trueRun the following command and set the -Enabled flag to $true:

Set-AzDiagnosticSetting  -ResourceId $account.ResourceId -StorageAccountId $sa.Id -Enabled $true -Categories DataPlaneRequests

该命令的输出应如以下示例所示:The output for the command should resemble the following sample:

    StorageAccountId            : /subscriptions/<subscription-ID>/resourceGroups/ContosoResourceGroup/providers`
    /Microsoft.Storage/storageAccounts/contosocosmosdblogs
    ServiceBusRuleId            :
    EventHubAuthorizationRuleId :
    Metrics
        TimeGrain       : PT1M
        Enabled         : False
        RetentionPolicy
        Enabled : False
        Days    : 0

    Logs
        Category        : DataPlaneRequests
        Enabled         : True
        RetentionPolicy
        Enabled : False
        Days    : 0

    WorkspaceId                 :
    Id                          : /subscriptions/<subscription-ID>/resourcegroups/ContosoResourceGroup/providers`
    /microsoft.documentdb/databaseaccounts/contosocosmosdb/providers/microsoft.insights/diagnosticSettings/service
    Name                        : service
    Type                        :
    Location                    :
    Tags                        :

该命令的输出确认数据库的日志记录现已启用,系统正在将信息保存到存储帐户。The output from the command confirms that logging is now enabled for your database and information is being saved to your storage account.

还可以选择性地为日志设置保留期策略,以便自动删除较旧的日志。Optionally, you can also set the retention policy for your logs, such that older logs are automatically deleted. 例如,将 -RetentionEnabled 标志设置为 $true,以设置保留策略。For example, set the retention policy with the -RetentionEnabled flag set to $true. -RetentionInDays 参数设置为 90,以便自动删除超过 90 天的日志。Set the -RetentionInDays parameter to 90 so that logs older than 90 days are automatically deleted.

Set-AzDiagnosticSetting -ResourceId $account.ResourceId`
 -StorageAccountId $sa.Id -Enabled $true -Categories DataPlaneRequests`
  -RetentionEnabled $true -RetentionInDays 90

访问日志Access your logs

DataPlaneRequests 类别的 Azure Cosmos DB 日志存储在所提供的存储帐户的 insights-logs-dataplanerequests 容器中。Azure Cosmos DB logs for the DataPlaneRequests category are stored in the insights-logs-dataplanerequests container in the storage account that you provided.

首先,请为容器名称创建一个变量。First, create a variable for the container name. 该变量将在整个演练中使用。The variable is used throughout the walk-through.

    $container = 'insights-logs-dataplanerequests'

若要列出此容器中的所有 Blob,请键入:To list all of the blobs in this container, type:

Get-AzStorageBlob -Container $container -Context $sa.Context

该命令的输出应如以下示例所示:The output for the command should resemble the following sample:

ICloudBlob        : Microsoft.WindowsAzure.Storage.Blob.CloudBlockBlob
BlobType          : BlockBlob
Length            : 10510193
ContentType       : application/octet-stream
LastModified      : 9/28/2017 7:49:04 PM +00:00
SnapshotTime      :
ContinuationToken:
Context           : Microsoft.WindowsAzure.Commands.Common.Storage.`
                    LazyAzureStorageContext
Name              : resourceId=/SUBSCRIPTIONS/<subscription-ID>/RESOURCEGROUPS/CONTOSORESOURCEGROUP/PROVIDERS`
/MICROSOFT.DOCUMENTDB/DATABASEACCOUNTS/CONTOSOCOSMOSDB/y=2017/m=09/d=28/h=19/m=00/PT1H.json

可从此输出中看出,blob 遵循以下命名约定:resourceId=/SUBSCRIPTIONS/<subscription-ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DOCUMENTDB/DATABASEACCOUNTS/<Database Account Name>/y=<year>/m=<month>/d=<day of month>/h=<hour>/m=<minute>/filename.jsonAs you can see from this output, the blobs follow a naming convention: resourceId=/SUBSCRIPTIONS/<subscription-ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DOCUMENTDB/DATABASEACCOUNTS/<Database Account Name>/y=<year>/m=<month>/d=<day of month>/h=<hour>/m=<minute>/filename.json

日期和时间值使用 UTC。The date and time values use UTC.

由于可使用相同的存储帐户收集多个资源的日志,因此,可以使用 Blob 名称中完全限定的资源 ID 来访问或下载所需的特定 Blob。Because the same storage account can be used to collect logs for multiple resources, you can use the fully qualified resource ID in the blob name to access and download the specific blobs that you need. 但在这样做之前,让我们先了解如何下载所有 Blob。Before we do that, we cover how to download all of the blobs.

首先,创建一个文件夹用于下载 Blob。First, create a folder to download the blobs. 例如:For example:

New-Item -Path 'C:\Users\username\ContosoCosmosDBLogs'`
 -ItemType Directory -Force

然后获取所有 Blob 的列表:Then, get a list of all of the blobs:

$blobs = Get-AzStorageBlob -Container $container -Context $sa.Context

通过 Get-AzStorageBlobContent 命令以管道传送此列表,将 Blob 下载到目标文件夹:Pipe this list through the Get-AzStorageBlobContent command to download the blobs into the destination folder:

$blobs | Get-AzStorageBlobContent `
 -Destination 'C:\Users\username\ContosoCosmosDBLogs'

运行第二个命令时,blob 名称中的 / 分隔符会在目标文件夹下创建完整的文件夹结构 。When you run this second command, the / delimiter in the blob names creates a full folder structure under the destination folder. 此文件夹结构用于下载 blob 并将其存储为文件。This folder structure is used to download and store the blobs as files.

若要选择性地下载 Blob,请使用通配符。To selectively download blobs, use wildcards. 例如:For example:

  • 如果有多个数据库,且只想下载名为 CONTOSOCOSMOSDB3 的数据库的日志,请使用以下命令:If you have multiple databases and want to download logs for just one database named CONTOSOCOSMOSDB3, use the command:

    Get-AzStorageBlob -Container $container `
     -Context $sa.Context -Blob '*/DATABASEACCOUNTS/CONTOSOCOSMOSDB3
    
  • 如果有多个资源组,并只想要下载其中某个资源组的日志,请使用命令 -Blob '*/RESOURCEGROUPS/<resource group name>/*'If you have multiple resource groups and want to download logs for just one resource group, use the command -Blob '*/RESOURCEGROUPS/<resource group name>/*':

    Get-AzStorageBlob -Container $container `
    -Context $sa.Context -Blob '*/RESOURCEGROUPS/CONTOSORESOURCEGROUP3/*'
    
  • 如果要下载 2017 年 7 月的所有日志,请使用命令 -Blob '*/year=2017/m=07/*'If you want to download all of the logs for the month of July 2017, use the command -Blob '*/year=2017/m=07/*':

    Get-AzStorageBlob -Container $container `
     -Context $sa.Context -Blob '*/year=2017/m=07/*'
    

也可以运行以下命令:You can also run the following commands:

  • 若要查询数据库资源的诊断设置状态,请使用命令 Get-AzDiagnosticSetting -ResourceId $account.ResourceIdTo query the status of diagnostic settings for your database resource, use the command Get-AzDiagnosticSetting -ResourceId $account.ResourceId.
  • 若要禁用数据库帐户资源的 DataPlaneRequests 类别的日志记录,请使用命令 Set-AzDiagnosticSetting -ResourceId $account.ResourceId -StorageAccountId $sa.Id -Enabled $false -Categories DataPlaneRequestsTo disable logging of the DataPlaneRequests category for your database account resource, use the command Set-AzDiagnosticSetting -ResourceId $account.ResourceId -StorageAccountId $sa.Id -Enabled $false -Categories DataPlaneRequests.

在其中每个查询中返回的 Blob 存储为文本,采用 JSON Blob 格式,如以下代码中所示:The blobs that are returned in each of these queries are stored as text and formatted as a JSON blob, as shown in the following code:

{
    "records":
    [
        {
           "time": "Fri, 23 Jun 2017 19:29:50.266 GMT",
           "resourceId": "contosocosmosdb",
           "category": "DataPlaneRequests",
           "operationName": "Query",
           "resourceType": "Database",
           "properties": {"activityId": "05fcf607-6f64-48fe-81a5-f13ac13dd1eb",`
           "userAgent": "documentdb-dotnet-sdk/1.12.0 Host/64-bit MicrosoftWindowsNT/6.2.9200.0 AzureSearchIndexer/1.0.0",`
           "resourceType": "Database","statusCode": "200","documentResourceId": "",`
           "clientIpAddress": "13.92.241.0","requestCharge": "2.260","collectionRid": "",`
           "duration": "9250","requestLength": "72","responseLength": "209", "resourceTokenUserRid": ""}
        }
    ]
}

若要了解每个 JSON blob 中的数据,请参阅解释 Azure Cosmos DB 日志To learn about the data in each JSON blob, see Interpret your Azure Cosmos DB logs.

管理日志Manage your logs

自执行 Azure Cosmos DB 操作起两小时,即可在帐户中使用诊断日志。Diagnostic Logs are made available in your account for two hours from the time that the Azure Cosmos DB operation was made. 存储帐户中的日志完全由你管理:It's up to you to manage your logs in your storage account:

  • 请使用标准的 Azure 访问控制方法保护日志并限制可访问日志的人员。Use standard Azure access control methods to secure your logs and restrict who can access them.
  • 删除不想继续保留在存储帐户中的日志。Delete logs that you no longer want to keep in your storage account.
  • 选择“记录 DataPlaneRequests”设置后,在门户中配置存档到存储帐户的数据平面请求的保留期。 The retention period for data plane requests that are archived to a Storage account is configured in the portal when the Log DataPlaneRequests setting is selected. 要更改此设置,请参阅在 Azure 门户中启用日志记录To change that setting, see Turn on logging in the Azure portal.

查看 Azure Monitor 日志中的日志View logs in Azure Monitor logs

如果在启用诊断日志记录时选择了“发送到 Log Analytics”选项,则容器中的诊断数据会在两个小时内转发到 Azure Monitor 日志 。If you selected the Send to Log Analytics option when you turned on diagnostic logging, diagnostic data from your container is forwarded to Azure Monitor logs within two hours. 如果在启用日志记录之后立即查看 Azure Monitor 日志,将看不到任何数据。When you look at Azure Monitor logs immediately after you turn on logging, you won't see any data. 请等待两小时,然后重试。Just wait two hours and try again.

在查看日志之前,请检查并确定 Log Analytics 工作区是否已升级为使用新的 Kusto 查询语言。Before you view your logs, check and see if your Log Analytics workspace has been upgraded to use the new Kusto query language. 若要检查,请打开 Azure 门户,在最左侧选择“Log Analytics 工作区”,然后选择工作区名称,如下图所示。 To check, open the Azure portal, select Log Analytics workspaces on the far left, then select the workspace name as shown in the next image. 此时会显示“Log Analytics 工作区” 页:The Log Analytics workspace page is displayed:

Azure 门户中的 Azure Monitor 日志

备注

OMS 工作区现在称为 Log Analytics 工作区。OMS workspaces are now referred to as Log Analytics workspaces.

如果“Log Analytics 工作区” 页上显示以下消息,则表示工作区尚未升级为使用新语言。If you see the following message on the Log Analytics workspace page, your workspace hasn't been upgraded to use the new language.

Azure Monitor 日志升级消息

若要查看 Azure Monitor 日志中的诊断数据,请打开左侧菜单中的“日志搜索”页或该页的“管理”区域,如下图所示: To view your diagnostic data in Azure Monitor logs, open the Log Search page from the left menu or the Management area of the page, as shown in the following image:

Azure 门户中的“日志搜索”选项

启用数据收集后,使用新的查询语言运行以下日志搜索示例,以查看最近的 10 条日志 AzureDiagnostics | take 10Now that you've enabled data collection, run the following log search example by using the new query language to see the 10 most recent logs AzureDiagnostics | take 10.

搜索最近 10 条日志的示例

查询Queries

可在“日志搜索”框中输入下面这些附加的查询,以帮助监视 Azure Cosmos 容器。 Here are some additional queries that you can enter into the Log search box to help you monitor your Azure Cosmos containers.

若要了解每个日志搜索返回的数据的含义,请参阅解释 Azure Cosmos DB 日志To learn about the meaning of the data that's returned by each log search, see Interpret your Azure Cosmos DB logs.

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

    AzureDiagnostics | where ResourceProvider=="MICROSOFT.DOCUMENTDB" and Category=="DataPlaneRequests"
    
  • 查询最近记录的 10 个事件:To query for the 10 most recently logged events:

    AzureDiagnostics | where ResourceProvider=="MICROSOFT.DOCUMENTDB" and Category=="DataPlaneRequests" | take 10
    
  • 查询已按操作类型分组的所有操作:To query for all operations, grouped by operation type:

    AzureDiagnostics | where ResourceProvider=="MICROSOFT.DOCUMENTDB" and Category=="DataPlaneRequests" | summarize count() by OperationName
    
  • 查询已按资源分组的所有操作:To query for all operations, grouped by Resource:

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

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

    备注

    此命令适用于活动日志,而不适用于诊断日志。This command is for an activity log, not a diagnostic log.

  • 查询哪些操作花费的时间超过 3 毫秒:To query for which operations take longer than 3 milliseconds:

    AzureDiagnostics | where toint(duration_s) > 3 and ResourceProvider=="MICROSOFT.DOCUMENTDB" and Category=="DataPlaneRequests" | summarize count() by clientIpAddress_s, TimeGenerated
    
  • 查询哪些代理正在运行操作:To query for which agent is running the operations:

    AzureDiagnostics | where ResourceProvider=="MICROSOFT.DOCUMENTDB" and Category=="DataPlaneRequests" | summarize count() by OperationName, userAgent_s
    
  • 查询何时执行了长时间运行的操作:To query for when the long running operations were performed:

    AzureDiagnostics | where ResourceProvider=="MICROSOFT.DOCUMENTDB" and Category=="DataPlaneRequests" | project TimeGenerated , duration_s | render timechart
    

解释日志Interpret your logs

存储在 Azure 存储和 Azure Monitor 日志中的诊断数据使用相似的架构。Diagnostic data that's stored in Azure Storage and Azure Monitor logs uses a similar schema.

下表介绍了每个日志项目的内容。The following table describes the content of each log entry.

Azure 存储字段或属性Azure Storage field or property Azure Monitor 日志属性Azure Monitor logs property 说明Description
timetime TimeGeneratedTimeGenerated 操作发生时的日期和时间 (UTC)。The date and time (UTC) when the operation occurred.
resourceIdresourceId 资源Resource 为其启用日志的 Azure Cosmos DB 帐户。The Azure Cosmos DB account for which logs are enabled.
categorycategory 类别Category 对于 Azure Cosmos DB 日志,DataPlaneRequests 是唯一可用的值。For Azure Cosmos DB logs, DataPlaneRequests is the only available value.
operationNameoperationName OperationNameOperationName 操作的名称。Name of the operation. 此值可以是以下任意操作:创建、更新、读取、ReadFeed、删除、替换、执行、SqlQuery、查询、JSQuery、Head、HeadFeed 或 Upsert。This value can be any of the following operations: Create, Update, Read, ReadFeed, Delete, Replace, Execute, SqlQuery, Query, JSQuery, Head, HeadFeed, or Upsert.
propertiesproperties 不适用n/a 下面的行中描述了此字段的内容。The contents of this field are described in the rows that follow.
activityIdactivityId activityId_gactivityId_g 日志记录操作的唯一 GUID。The unique GUID for the logged operation.
userAgentuserAgent userAgent_suserAgent_s 一个字符串,指定执行请求的客户端用户代理。A string that specifies the client user agent that's performing the request. 格式为 {用户代理名}/{版本}。The format is {user agent name}/{version}.
requestResourceTyperequestResourceType requestResourceType_srequestResourceType_s 所访问资源的类型。The type of the resource accessed. 此值可以是以下任意资源类型:数据库、容器、文档、附件、用户、权限、StoredProcedure、触发器、UserDefinedFunction 或产品/服务。This value can be any of the following resource types: Database, Container, Document, Attachment, User, Permission, StoredProcedure, Trigger, UserDefinedFunction, or Offer.
statusCodestatusCode statusCode_sstatusCode_s 操作的响应状态。The response status of the operation.
requestResourceIdrequestResourceId ResourceIdResourceId 与请求相关的 resourceId。The resourceId that pertains to the request. 值可以指向 databaseRid、collectionRid 或 documentRid(具体取决于所执行的操作)。The value may point to databaseRid, collectionRid, or documentRid depending on the operation performed.
clientIpAddressclientIpAddress clientIpAddress_sclientIpAddress_s 客户端的 IP 地址。The client's IP address.
requestChargerequestCharge requestCharge_srequestCharge_s 操作使用的 RU 数目The number of RUs that are used by the operation
collectionRidcollectionRid collectionId_scollectionId_s 集合的唯一 ID。The unique ID for the collection.
durationduration duration_sduration_s 操作持续时间,以毫秒为单位。The duration of the operation, in milliseconds.
requestLengthrequestLength requestLength_srequestLength_s 请求的长度(按字节计)。The length of the request, in bytes.
responseLengthresponseLength responseLength_sresponseLength_s 响应的长度(按字节计)。The length of the response, in bytes.
resourceTokenUserRidresourceTokenUserRid resourceTokenUserRid_sresourceTokenUserRid_s 资源令牌用于身份验证时,此值非空。This value is non-empty when resource tokens are used for authentication. 值指向用户的资源 ID。The value points to the resource ID of the user.

后续步骤Next steps