Azure の診断設定を使用して Azure Cosmos DB データを監視する

[アーティクル]
11/08/2023

適用対象: NoSQL MongoDB Cassandra Gremlin Table

Azure の診断設定は、リソースログの収集に使用されます。リソースからは Azure リソースログが出力され、そのリソースの操作に関する豊富なデータが頻繁に提供されます。これらのログは、要求ごとに取得され、"データプレーンログ" とも呼ばれます。データプレーン操作の例としては、delete、insert、readFeed などがあります。これらのログの内容は、リソースの種類によって異なります。

プラットフォームメトリックとアクティビティログは自動的に収集されますが、リソースログを収集したり、それらを Azure Monitor の外部に転送したりするには、診断設定を作成する必要があります。 Azure Cosmos DB アカウントの診断設定を有効にしてリソースログを次のソースに送信できます。

Log Analytics ワークスペース
- Log Analytics に送信されるデータを、Azure Diagnostics (レガシ) またはリソース固有(プレビュー) のテーブルに書き込むことができます
イベントハブ
ストレージアカウント

Note

REST API を介して診断設定を作成するための手順に従って、診断設定をリソース固有のモードで作成することをお勧めします (Table 用 API を除くすべての API の場合)。このオプションを使用するとさらなるコスト最適化が得られ、データ処理のビューも向上します。

前提条件

既存の Azure Cosmos DB アカウント。
- Azure サブスクリプションをお持ちの場合は、新しいアカウントを作成します。
- Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。
- または、コミットする前に Azure Cosmos DB を無料で試すこともできます。

診断設定の作成

ここでは、アカウントの診断設定を作成するプロセスについて説明します。

Azure portal にサインインします。
Azure Cosmos DB アカウントに移動します。 [監視]セクションの [診断設定] ペインを開き、[診断設定の追加] オプションを選択します。

重要

フルテキストクエリ 機能が自分のアカウントで有効になっていない場合は、"フルテキストクエリ [...] を有効にして詳細なログ記録を行う" というプロンプトが表示される場合があります。この機能を有効にしない場合は、この警告を無視しても問題ありません。詳細については、「フルテキストクエリを有効にする」を参照してください。

[診断設定] ウィンドウで、フォームに希望のカテゴリを入力します。ログカテゴリの一覧を次に示します。

カテゴリ	API	定義	キープロパティ
DataPlaneRequests	NoSQL 用 API に推奨	データプレーン操作としてバックエンド要求をログに記録します。これは、アカウント内のデータを作成、更新、削除、または取得するために実行される要求です。	`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	このテーブルは、NoSQL 用 API アカウントに対して実行されるクエリ操作の詳細を示します。既定では、クエリテキストとそのパラメータは難読化されるため、要求によって利用可能なフルテキストクエリログ記録に個人データがログ記録されることが防止されます。	`databasename`、`partitionkeyrangeid`、`querytext`
PartitionKeyStatistics	すべての API	論理パーティションキーの統計情報を、パーティションキーの推定ストレージサイズ (KB) を示すことにより、ログ記録します。この表は、ストレージスキューをトラブルシューティングするときに便利です。この PartitionKeyStatistics ログは、次の条件に該当する場合にのみ出力されます。1. 物理パーティション内のドキュメントの少なくとも 1% が同じ論理パーティションキーを持っている。 2. 物理パーティション内のすべてのキーのうち、ストレージサイズが最も大きい上位 3 つのキーが PartitionKeyStatistics ログによってキャプチャされる。前の条件が満たされていない場合、パーティションキーの統計データは使用できません。アカウントで上記の条件が満たされていなくても問題ありません。通常、これは論理パーティションのストレージスキューがないことを示しています。注: パーティションキーの推定サイズは、物理パーティション内のドキュメントが概ね同じサイズであると想定するサンプリングアプローチを使用して計算されます。物理パーティション内のドキュメントのサイズが均一でない場合、パーティションキーの推定サイズが正確でなくなる可能性があります。	`subscriptionId`、`regionName`、`partitionKey`, `sizeKB`
PartitionKeyRUConsumption	NoSQL 用 API または Apache Gremlin 用 API	パーティションキーの RU (秒単位) の合計消費量をログに記録します。この表は、ホットパーティションのトラブルシューティングで役立ちます。現在、Azure Cosmos DB では、NoSQL 用 API アカウントの場合にのみ、ポイントの読み取りまたは書き込み、クエリとストアドプロシージャ操作について、パーティションキーが報告されます。	`subscriptionId`、`regionName`、`partitionKey`、`requestCharge`、`partitionKeyRangeId`
ControlPlaneRequests	すべての API	アカウントの作成、リージョンの追加または削除、アカウントのレプリケーション設定の更新など、コントロールプレーンの操作に関する詳細をログに記録します。	`operationName`、`httpstatusCode`、`httpMethod`, `region`
TableApiRequests	Table 用 API	Azure Cosmos DB for Table への要求を処理するために、ユーザーがフロントエンドから開始した要求をログします。	`operationName`、`requestCharge`、`piiCommandText`

カテゴリの詳細を選択したら、適切な宛先にログを送信します。 Log Analytics ワークスペースにログを送信する場合は、[対象テーブル] で [リソース固有] を選択してください。

Azure CLI を使用して診断設定を作成するには、az monitor diagnostic-settings create コマンドを使用します。パラメーターの説明については、このコマンドのドキュメントを参照してください。

Note

NoSQL 用 API を使っている場合は、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 Monitor REST API を、対話型コンソールを介して診断設定を作成するために使用します。

Note

logAnalyticsDestinationType プロパティを Dedicated に設定してリソース固有のテーブルを有効にすることをお勧めします。

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`

Note

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) テンプレートを使用して診断設定を作成します。

Note

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

クエリテキストをログに記録するためにフルテキストクエリを有効にする

Note

この機能を有効にすると、追加のログコストが発生することがあります。料金の詳細については「Azure Monitor の価格」を参照してください。トラブルシューティングを行った後に、この機能を無効にすることをお勧めします。

Azure Cosmos DB では、詳細なトラブルシューティングのために機能拡張されたログ記録が提供されます。フルテキストクエリを有効にすると、Azure Cosmos DB アカウント内のすべての要求で、難読化解除されたクエリを表示できます。また、ログ内のこのデータにアクセスして表示するためのアクセス許可を Azure Cosmos DB に付与します。

Azure Portal
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 と HTTP GET 動詞を指定した 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": "None"
  }
}
```
フルテキストクエリがまだ有効になっていない場合は、HTTP PATCH 動詞と JSON ペイロードを指定して az rest をもう一度使用して有効にします。
```
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 データを監視する

前提条件

診断設定の作成

クエリ テキストをログに記録するためにフルテキスト クエリを有効にする

クエリ データ

次のステップ

その他のリソース

クエリテキストをログに記録するためにフルテキストクエリを有効にする

クエリデータ