使用 Azure Monitor Log Analytics 诊断设置监视 Azure Cosmos DB 数据

2025-09-21

适用对象： NoSQL MongoDB Cassandra Gremlin 表

可以使用诊断设置在 Azure 中收集资源日志。资源生成 Azure 资源日志，并提供有关该资源操作的丰富、频繁的数据。这些日志是按请求捕获的，也称为“数据平面日志”。部分数据平面操作的示例包括 delete、insert 和 readFeed。这些日志的内容因资源类型而异。

若要了解有关诊断设置的详细信息，请参阅 Azure Monitor 中的诊断设置。

注意

建议按照 REST API 选项卡中的说明，在特定于资源模式下创建诊断设置（适用于除表 API 之外的所有 API）。此选项通过改进的数据处理视图提供了额外的成本优化。

先决条件

现有的 Azure Cosmos DB 帐户。
- 如果你有 Azure 订阅，请创建一个新帐户。
- 如果没有 Azure 订阅，请在开始前创建一个试用版订阅。
现有的 Azure Monitor Log Analytics 工作区。

警告

如果需要删除、重命名或移动资源，或跨资源组或订阅迁移资源，请先删除其诊断设置。否则，如果重新创建此资源，则已删除资源的诊断设置可能包含在新资源中，具体取决于每个资源的资源配置。如果诊断设置包含在新资源中，则会恢复诊断设置中定义的资源日志收集，并将适用的指标和日志数据发送到先前配置的目标。

此外，为了保持环境整洁，最好删除将要删除且不打算再次使用的资源的诊断设置。

创建诊断设置

我们将在此演练为帐户创建诊断设置的过程。

注意

目前不支持将指标作为类别导出到日志。

登录到 Azure 门户。
导航到现有的 Azure Cosmos DB 帐户。
在资源菜单的“监视”部分，选择“诊断设置”。然后，选择“添加诊断设置”选项。

重要

您可能会提示您“启用全文查询以获得更详细的日志记录”，如果您的帐户尚未启用 全文查询 功能。如果不想启用此功能，可以安全地忽略此警告。有关详细信息，请参阅启用全文查询。
在“诊断设置”窗格中，将设置命名为“example-setting”，然后选择“QueryRuntimeStatistics”类别。启用“发送到 Log Analytics 工作区”复选框，选择你现有的工作区。最后，选择“特定于资源”作为目标选项。

在 Azure CLI 中使用 az monitor diagnostic-settings create 命令来创建诊断设置。若要了解命令的参数，请参阅文档。

确保登录到 Azure CLI。有关详细信息，请参阅使用 Azure CLI 登录。

使用 az monitor diagnostic-settings create 创建设置。

az monitor diagnostic-settings create \
  --resource $(az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "id" \
    --output "tsv" \
  ) \
  --workspace $(az monitor log-analytics workspace show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "id" \
    --output "tsv" \
  ) \
  --name "example-setting" \
  --export-to-resource-specific true \
  --logs '[
    {
      "category": "QueryRuntimeStatistics",
      "enabled": true
    }
  ]'

重要

此示例使用 --export-to-resource-specific 参数来启用特定于资源的表。

查看使用 az monitor diagnostics-settings show 创建新设置的结果。

az monitor diagnostic-settings show \
  --name "example-setting" \
  --resource $(az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "id" \
    --output "tsv" \
  )

使用 Azure Monitor REST API 通过交互式控制台创建诊断设置。

确保登录到 Azure CLI。有关详细信息，请参阅使用 Azure CLI 登录。

使用 HTTP PUT 请求和 az rest 为 Azure Cosmos DB 资源创建诊断设置。

diagnosticSettingName="example-setting"

resourceId=$(az cosmosdb show \
  --resource-group "<resource-group-name>" \
  --name "<account-name>" \
  --query "id" \
  --output "tsv" \
)

workspaceId=$(az monitor log-analytics workspace show \
  --resource-group "<resource-group-name>" \
  --name "<account-name>" \
  --query "id" \
  --output "tsv" \
)

az rest \
  --method "PUT" \
  --url "$resourceId/providers/Microsoft.Insights/diagnosticSettings/$diagnosticSettingName" \
  --url-parameters "api-version=2021-05-01-preview" \
  --body '{
    "properties": {
      "workspaceId": "'"$workspaceId"'",
      "logs": [
        {
          "category": "QueryRuntimeStatistics",
          "enabled": true
        }
      ],
      "logAnalyticsDestinationType": "Dedicated"
    }
  }'

重要

此示例将 logAnalyticsDestinationType 属性设置为 Dedicated 以启用特定于资源的表。

再次使用 az rest 以及 HTTP GET 谓词，以获取诊断设置的属性。

diagnosticSettingName="example-setting"

resourceId=$(az cosmosdb show \
  --resource-group "<resource-group-name>" \
  --name "<account-name>" \
  --query "id" \
  --output "tsv" \
)

az rest \
  --method "GET" \
  --url "$resourceId/providers/Microsoft.Insights/diagnosticSettings/$diagnosticSettingName" \
  --url-parameters "api-version=2021-05-01-preview"

使用 Bicep 模板创建诊断设置。

确保登录到 Azure CLI。有关详细信息，请参阅使用 Azure CLI 登录。
创建名为 diagnosticSetting.bicep 的新文件。

输入以下用于为 Azure Cosmos DB 资源部署诊断设置的 Bicep 模板内容。

@description('The name of the diagnostic setting to create.')
param diagnosticSettingName string = 'example-setting'

@description('The name of the Azure Cosmos DB account to monitor.')
param azureCosmosDbAccountName string

@description('The name of the Azure Monitor Log Analytics workspace to use.')
param logAnalyticsWorkspaceName string

resource azureCosmosDbAccount 'Microsoft.DocumentDB/databaseAccounts@2021-06-15' existing = {
  name: azureCosmosDbAccountName
}

resource logAnalyticsWorkspace 'Microsoft.OperationalInsights/workspaces@2023-09-01' existing = {
  name: logAnalyticsWorkspaceName
}

resource diagnosticSetting 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = {
  name: diagnosticSettingName
  scope: azureCosmosDbAccount
  properties: {
    workspaceId: logAnalyticsWorkspace.id
    logAnalyticsDestinationType: 'Dedicated'
    logs: [
      {
        category: 'QueryRuntimeStatistics'
        enabled: true
      }
    ]
  }
}

重要

此示例将 logAnalyticsDestinationType 属性设置为 Dedicated 以启用特定于资源的表。

使用 az deployment group create 部署模板。

az deployment group create \
    --resource-group "<resource-group-name>" \
    --template-file diagnosticSetting.bicep \
    --parameters \
      azureCosmosDbAccountName="<azure-cosmos-db-account-name>" \
      logAnalyticsWorkspaceName="<log-analytics-workspace-name>"

提示

使用 az bicep build 命令将 Bicep 模板转换为 Azure 资源管理器模板。

使用 Azure 资源管理器模板创建诊断设置。

确保登录到 Azure CLI。有关详细信息，请参阅使用 Azure CLI 登录。
创建名为 diagnosticSetting.bicep 的新文件。

输入以下用于为 Azure Cosmos DB 资源部署诊断设置的 Azure 资源管理器模板内容。

{
  "$schema": "<https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#>",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "diagnosticSettingName": {
      "type": "string",
      "defaultValue": "example-setting",
      "metadata": {
        "description": "The name of the diagnostic setting to create."
      }
    },
    "azureCosmosDbAccountName": {
      "type": "string",
      "metadata": {
        "description": "The name of the Azure Cosmos DB account to monitor."
      }
    },
    "logAnalyticsWorkspaceName": {
      "type": "string",
      "metadata": {
        "description": "The name of the Azure Monitor Log Analytics workspace to use."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Insights/diagnosticSettings",
      "apiVersion": "2021-05-01-preview",
      "scope": "[format('Microsoft.DocumentDB/databaseAccounts/{0}', parameters('azureCosmosDbAccountName'))]",
      "name": "[parameters('diagnosticSettingName')]",
      "properties": {
        "workspaceId": "[resourceId('Microsoft.OperationalInsights/workspaces', parameters('logAnalyticsWorkspaceName'))]",
        "logAnalyticsDestinationType": "Dedicated",
        "logs": [
          {
            "category": "QueryRuntimeStatistics",
            "enabled": true
          }
        ]
      }
    }
  ]
}

重要

此示例将 logAnalyticsDestinationType 属性设置为 Dedicated 以启用特定于资源的表。

使用 az deployment group create 部署模板。

az deployment group create \
    --resource-group "<resource-group-name>" \
    --template-file azuredeploy.json \
    --parameters \
      azureCosmosDbAccountName="<azure-cosmos-db-account-name>" \
      logAnalyticsWorkspaceName="<log-analytics-workspace-name>"

提示

使用 az bicep decompile 命令将 Azure 资源管理器模板转换为 Bicep 模板。

启用日志记录查询文本的全文查询功能

Azure Cosmos DB 提供高级日志记录以进行详细的故障排除。启用全文查询功能后，你将能够查看 Azure Cosmos DB 帐户中所有请求的已取消模糊处理的查询。你还将为 Azure Cosmos DB 提供权限，以访问并在日志中显示此数据。

警告

启用此功能可能会导致额外的日志记录成本。有关定价详细信息，请参阅 Azure Monitor 定价。建议在故障排除后禁用此功能。

Azure 门户
Azure CLI / REST API / Bicep / ARM 模板

在现有的 Azure Cosmos DB 帐户页上，选择资源菜单“设置”部分中的“功能”选项。然后，选择“诊断全文查询”功能。
在对话框中，选择“Enable”。此设置将在几分钟内应用。所有新引入的日志现在都具有每个请求的全文或 PIICommand 文本。

使用 Azure CLI 为 Azure Cosmos DB 帐户启用全文查询。

再次使用 az rest 以及 HTTP PATCH 谓词和 JSON 有效负载来启用全文查询。

az rest \
  --method "PATCH" \
  --url $(az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "id" \
    --output "tsv" \
  ) \
  --url-parameters "api-version=2021-05-01-preview" \
  --body '{
    "properties": {
      "diagnosticLogSettings": {
        "enableFullTextQuery": "True"
      }
    }
  }'

请等待几分钟，以便操作完成。再次使用 az rest 以及 HTTP GET 来检查全文查询的状态。

az rest \
  --method "GET" \
  --url $(az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "id" \
    --output "tsv" \
  ) \
  --url-parameters "api-version=2021-05-01-preview" \
  --query "{accountName:name,fullTextQueryEnabled:properties.diagnosticLogSettings.enableFullTextQuery}"

输出应类似于以下示例。

{
  "accountName": "<account-name>",
  "fullTextQueryEnabled": "True"
}

共用方式為

使用 Azure Monitor Log Analytics 诊断设置监视 Azure Cosmos DB 数据

先决条件

创建诊断设置

启用日志记录查询文本的全文查询功能

相关内容

其他資源