使用 Azure 中的診斷設定來監視 Azure Cosmos DB 資料

發行項
03/12/2024

適用於：NoSQL MongoDB Cassandra Gremlin Table

Azure 中的診斷設定可用來收集資源記錄。資源會發出 Azure 資源記錄，並提供該資源作業的豐富、經常性資料。這些記錄會依要求進行擷取，也稱為「資料平面記錄」。資料平面作業的一些範例包括刪除、插入和 readFeed。這些記錄的內容會依資源類型而有所不同。

系統會自動收集平台計量和活動記錄，您必須建立診斷設定來收集資源記錄，或將其轉送到 Azure 監視器外部。您可以開啟 Azure Cosmos DB 帳戶的診斷設定，並將資源記錄傳送至下列來源：

Log Analytics 工作區
- 傳送至 Log Analytics 的資料可以寫入 Azure 診斷 (舊版) 或資源專屬 (預覽) 資料表
事件中樞
儲存體帳戶

注意

建議您在資源專屬模式中建立診斷設定 (適用於 API for Table 以外的所有 API)，遵循我們透過 REST API 建立診斷設定的指示。此選項提供額外的成本最佳化，具有可用於處理資料的改良檢視。

必要條件

現有的 Azure Cosmos DB 帳戶。
- 如果您有 Azure 訂用帳戶，則請建立新的帳戶。
- 如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
- 或者，您可以在認可之前免費試用 Azure Cosmos DB。

建立診斷設定

在這裡，我們會逐步解說建立帳戶診斷設定的程序。

登入 Azure 入口網站。
瀏覽至 Azure Cosmos DB 帳戶。開啟 [監視] 區段下方的 [診斷設定] 窗格，然後選取 [新增診斷設定] 選項。

重要

如果帳戶中未啟用「全文檢索查詢」功能，則您可能會看到「啟用全文檢索查詢 [...] 以取得更詳細的記錄」提示。如果您不想要啟用此功能，則可以放心地忽略此警告。如需詳細資訊，請參閱啟用全文檢索查詢。

在 [診斷設定] 窗格中，使用您慣用的類別來填入表單。以下包含的是記錄類別的清單。

類別	API	定義	索引鍵內容
DataPlaneRequests	建議用於 API for NoSQL	將後端要求記錄為資料平面作業，即為建立、更新、刪除或擷取帳戶中資料而執行的要求。	`Requestcharge`、`statusCode`、`clientIPaddress`、`partitionID`、`resourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	適用於 MongoDB 的 API	從前端記錄使用者起始的要求，為 Azure Cosmos DB for MongoDB 要求提供服務。當您啟用此類別時，請務必停用 DataPlaneRequests。	`Requestcharge`, `opCode`, `retryCount`, `piiCommandText`
CassandraRequests	適用於 Apache Cassandra 的 API	從前端記錄使用者起始的要求，為 Azure Cosmos DB for Cassandra 要求提供服務。	`operationName`、`requestCharge`、`piiCommandText`
GremlinRequests	適用於 Apache Gremlin 的 API	從前端記錄使用者起始的要求，為 Azure Cosmos DB for Gremlin 要求提供服務。	`operationName`, `requestCharge`, `piiCommandText`, `retriedDueToRateLimiting`
QueryRuntimeStatistics	適用於 NoSQL 的 API	下表詳細說明針對 API for NoSQL 帳戶執行的查詢作業。根據預設，系統會將查詢文字和其參數模糊化，以避免透過要求所提供的全文檢索查詢記錄來記錄個人資料。	`databasename`、`partitionkeyrangeid`、`querytext`
PartitionKeyStatistics	所有 API	藉由表示分割區索引鍵的預估儲存體大小 (KB)，記錄邏輯分割區索引鍵的統計資料。當您針對儲存體誤差進行疑難排解時，此資料表很有用。只有在下列條件成立時，才會發出這個 PartitionKeyStatistics 記錄：1. 實體分割區中至少有 1% 的文件具有相同的邏輯分割區索引鍵。 2. 在實體分割區的所有索引鍵中，PartitionKeyStatistics 記錄會擷取儲存體大小最大的前三個索引鍵。如果不符合上述條件，則無法使用分割區索引鍵統計資料。如果您的帳戶不符合上述條件也沒有關係，這通常表示您沒有邏輯分割區儲存體誤差。注意：分割區索引鍵的預估大小會使用取樣方法來計算，該方法會假設實體分割區中的文件大小大致相同。如果文件大小在實體分割區中不是統一的，則預估分割區索引鍵大小可能不正確。	`subscriptionId`, `regionName`, `partitionKey`, `sizeKB`
PartitionKeyRUConsumption	API for NoSQL 或 API for Apache Gremlin	記錄分割區索引鍵的每秒彙總 RU/秒耗用量。針對常用資料分割進行疑難排解時，此資料表很有用。目前，Azure Cosmos DB 僅針對 API for NoSQL 帳戶和點讀取/寫入、查詢和預存程序作業，報告分割區索引鍵。	`subscriptionId`, `regionName`, `partitionKey`, `requestCharge`, `partitionKeyRangeId`
ControlPlaneRequests	所有 API	記錄有關控制平面作業的詳細資料，其中包括建立帳戶、新增或移除區域、更新帳戶複寫設定等。	`operationName`, `httpstatusCode`, `httpMethod`, `region`
TableApiRequests	適用於資料表的 API	從前端記錄使用者起始的要求，為 Azure Cosmos DB for Table 要求提供服務。	`operationName`、`requestCharge`、`piiCommandText`

當您選取類別詳細資料之後，請將記錄傳送至慣用的目的地。如果您要將記錄傳送至 Log Analytics 工作區，請務必選取 [資源專屬] 作為目的地資料表。

透過 Azure CLI 使用 az monitor diagnostic-settings create 命令，建立診斷設定。請參閱此命令的文件，以瞭解其參數的描述。

注意

如果您使用 API for NoSQL，建議將 export-to-resource-specific 屬性設定為 true。

建立 subscriptionId、diagnosticSettingName、workspaceName 和 resourceGroupName 的殼層變數。

# Variable for subscription id
subscriptionId="<subscription-id>"

# Variable for resource group name
resourceGroupName="<resource-group-name>"

# Variable for workspace name
workspaceName="<workspace-name>"

# Variable for diagnostic setting name
diagnosticSettingName="<diagnostic-setting-name>"

使用 az monitor diagnostic-settings create 建立設定。

az monitor diagnostic-settings create \
    --resource "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDb/databaseAccounts/" \
    --name $diagnosticSettingName \
    --export-to-resource-specific true \
    --logs '[{"category": "QueryRuntimeStatistics","categoryGroup": null,"enabled": true,"retentionPolicy": {"enabled": false,"days": 0}}]' \
    --workspace "/subscriptions/$subscriptionId/resourcegroups/$resourceGroupName/providers/microsoft.operationalinsights/workspaces/$workspaceName"

使用 Azure 監視器 REST API，透過互動式主控台建立診斷設定。

注意

建議將 logAnalyticsDestinationType 屬性設定為專用，以啟用資源專屬資料表。

建立 HTTP PUT 要求。

PUT
https://management.azure.com/{resource-id}/providers/microsoft.insights/diagnosticSettings/service?api-version={api-version}

請使用這些標頭搭配要求。

參數/標頭	值/描述
name	診斷設定的名稱。
resourceUri	Azure Cosmos DB 帳戶的 Microsoft Insights 子資源 URI。
api-version	`2017-05-01-preview`
Content-Type	`application/json`

注意

Microsoft Insights 子資源的 URI 格式為： subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}。如需 Azure Cosmos DB 資源 URI 的詳細資訊，請參閱 Azure Cosmos DB REST API 的資源 URI 語法。

將要求的主體設定為此 JSON 承載。

{
    "id": "/subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}",
    "type": "Microsoft.Insights/diagnosticSettings",
    "name": "name",
    "location": null,
    "kind": null,
    "tags": null,
    "properties": {
        "storageAccountId": null,
        "serviceBusRuleId": null,
        "workspaceId": "/subscriptions/{SUBSCRIPTION_ID}/resourcegroups/{RESOURCE_GROUP}/providers/microsoft.operationalinsights/workspaces/{WORKSPACE_NAME}",
        "eventHubAuthorizationRuleId": null,
        "eventHubName": null,
        "logs": [
            {
                "category": "DataPlaneRequests",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "QueryRuntimeStatistics",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "PartitionKeyStatistics",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "PartitionKeyRUConsumption",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            },
            {
                "category": "ControlPlaneRequests",
                "categoryGroup": null,
                "enabled": true,
                "retentionPolicy": {
                    "enabled": false,
                    "days": 0
                }
            }
        ],
        "logAnalyticsDestinationType": "Dedicated"
    },
    "identity": null
}

在這裡，使用 Azure Resource Manager (ARM) 範本來建立診斷設定。

注意

將 logAnalyticsDestinationType 屬性設定為 Dedicated，以啟用資源特定資料表。

建立下列 JSON 範本檔案，以部署 Azure Cosmos DB 資源的診斷設定。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "settingName": {
      "type": "string",
      "metadata": {
        "description": "The name of the diagnostic setting."
      }
    },
    "dbName": {
      "type": "string",
      "metadata": {
        "description": "The name of the database."
      }
    },
    "workspaceId": {
      "type": "string",
      "metadata": {
        "description": "The resource Id of the workspace."
      }
    },
    "storageAccountId": {
      "type": "string",
      "metadata": {
        "description": "The resource Id of the storage account."
      }
    },
    "eventHubAuthorizationRuleId": {
      "type": "string",
      "metadata": {
        "description": "The resource Id of the event hub authorization rule."
      }
    },
    "eventHubName": {
      "type": "string",
      "metadata": {
        "description": "The name of the event hub."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Insights/diagnosticSettings",
      "apiVersion": "2021-05-01-preview",
      "scope": "[format('Microsoft.DocumentDB/databaseAccounts/{0}', parameters('dbName'))]",
      "name": "[parameters('settingName')]",
      "properties": {
        "workspaceId": "[parameters('workspaceId')]",
        "storageAccountId": "[parameters('storageAccountId')]",
        "eventHubAuthorizationRuleId": "[parameters('eventHubAuthorizationRuleId')]",
        "eventHubName": "[parameters('eventHubName')]",
        "logAnalyticsDestinationType": "[parameters('logAnalyticsDestinationType')]",
        "logs": [
          {
            "category": "DataPlaneRequests",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "MongoRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "QueryRuntimeStatistics",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "PartitionKeyStatistics",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "PartitionKeyRUConsumption",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "ControlPlaneRequests",
            "categoryGroup": null,
            "enabled": true,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "CassandraRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "GremlinRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          },
          {
            "category": "TableApiRequests",
            "categoryGroup": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            }
          }
        ],
        "metrics": [
          {
            "timeGrain": null,
            "enabled": false,
            "retentionPolicy": {
              "days": 0,
              "enabled": false
            },
            "category": "Requests"
          }
        ]
      }
    }
  ]
}

使用您 Azure Cosmos DB 資源適用的設定來建立下列 JSON 參數檔案。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "settingName": {
      "value": "{DIAGNOSTIC_SETTING_NAME}"
    },
    "dbName": {
      "value": "{ACCOUNT_NAME}"
    },
    "workspaceId": {
      "value": "/subscriptions/{SUBSCRIPTION_ID}/resourcegroups/{RESOURCE_GROUP}/providers/microsoft.operationalinsights/workspaces/{WORKSPACE_NAME}"
    },
    "storageAccountId": {
      "value": "/subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.Storage/storageAccounts/{STORAGE_ACCOUNT_NAME}"
    },
    "eventHubAuthorizationRuleId": {
      "value": "/subscriptions/{SUBSCRIPTION_ID}/resourcegroups{RESOURCE_GROUP}/providers/Microsoft.EventHub/namespaces/{EVENTHUB_NAMESPACE}/authorizationrules/{EVENTHUB_POLICY_NAME}"
    },
    "eventHubName": {
      "value": "{EVENTHUB_NAME}"
    },
    "logAnalyticsDestinationType": {
      "value": "Dedicated"
    }
  }
}

使用 az deployment group create 來部署範本。

az deployment group create \
    --resource-group <resource-group-name> \
    --template-file <path-to-template>.json \
    --parameters @<parameters-file-name>.json

啟用記錄查詢文字的全文檢索查詢

注意

啟用這項功能可能會導致額外的記錄成本，如需定價詳細資料，請造訪 Azure 監視器定價。建議您在疑難排解之後停用此功能。

Azure Cosmos DB 提供進階記錄，以進行詳細疑難排解。啟用全文檢索查詢，您可以在 Azure Cosmos DB 帳戶內檢視所有要求的去模糊化查詢。您也會授與 Azure Cosmos DB 存取權，以在您的記錄中存取和呈現此資料。

Azure 入口網站
Azure CLI/REST API/ARM 範本

若要啟用這項功能，請瀏覽至 Azure Cosmos DB 帳戶中的 Features 頁面。
選取 Enable。此設定會在幾分鐘內套用。所有新內嵌的記錄都會有每個要求的全文檢索或 PIICommand 文字。

確定您已登入 Azure CLI。如需詳細資訊，請參閱使用 Azure CLI 登入。或者，請確定您已為 CLI 設定使用中的訂用帳戶。如需詳細資訊，請參閱變更使用中的 Azure CLI 訂用帳戶。

建立 accountName 和 resourceGroupName 的殼層變數。

# Variable for resource group name
resourceGroupName="<resource-group-name>"

# Variable for account name
accountName="<account-name>"

使用 az show 取得您現有帳戶的唯一識別碼。

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query id

將唯一識別碼存放在名稱為 $uri 的殼層變數中。

uri=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $accountName \
        --query id \
        --output tsv
)

搭配使用 REST API 和 az rest 與 HTTP GET 指令動詞來查詢資源，以檢查是否已啟用全文檢索查詢。

az rest \
    --method GET \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --query "{accountName:name,fullTextQuery:{state:properties.diagnosticLogSettings.enableFullTextQuery}}"

如果未啟用全文檢索查詢，則輸出會與此範例類似。

{
  "accountName": "<account-name>",
  "fullTextQuery": {
    "state": "None"
  }
}

如果尚未啟用全文檢索查詢，請再次使用 az rest 搭配 HTTP PATCH 動詞命令以及 JSON 承載。
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
注意

如果您要在 PowerShell 提示內使用 Azure CLI，則需要使用反斜線 (\) 字元來逸出雙引號。

請稍候，完成此作業需要幾分鐘。再次使用 az rest 來檢查全文檢索查詢的狀態。

az rest \
    --method GET \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --query "{accountName:name,fullTextQuery:{state:properties.diagnosticLogSettings.enableFullTextQuery}}"

輸出應類似於此範例。

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

查詢資料

若要了解如何使用這些新啟用的功能進行查詢，請參閱：

下一步

監視 Azure Cosmos DB 資料參考

使用 Azure 中的診斷設定來監視 Azure Cosmos DB 資料

必要條件

建立診斷設定

啟用記錄查詢文字的全文檢索查詢

查詢資料

下一步

其他資源