Azure에서 진단 설정을 사용하여 Azure Cosmos DB 데이터 모니터링

적용 대상: NoSQL MongoDB Cassandra Gremlin 테이블

Azure의 진단 설정은 리소스 로그를 수집하는 데 사용됩니다. 리소스는 Azure 리소스 로그를 내보내고, 해당 리소스의 작업에 대한 풍부하고 빈도 높은 데이터를 제공합니다. 이러한 로그는 요청별로 캡처되며 “데이터 평면 로그”라고도 불립니다. 데이터 평면 작업의 몇 가지 예로는 delete, insert 및 readFeed가 있습니다. 이러한 로그의 내용은 리소스 종류에 따라 달라집니다.

플랫폼 메트릭과 활동 로그는 자동으로 수집되지만 리소스 로그를 수집하거나 Azure Monitor 외부로 전달 하려면 진단 설정을 만들어야 합니다. Azure Cosmos DB 계정에 대한 진단 설정을 활성화하고 다음 원본에 리소스 로그를 보낼 수 있습니다.

• Log Analytics 작업 영역
  • Log Analytics로 전송된 데이터를 Azure 진단(레거시) 또는 리소스 관련(미리 보기) 표에 쓸 수 있습니다
• 이벤트 허브
• 스토리지 계정

참고 항목

REST API를 통한 진단 설정 생성에 대한 지침에 따라 리소스별 모드(Table용 API를 제외한 모든 API에 대해)에서 진단 설정을 생성하는 것이 좋습니다. 이 옵션은 데이터 처리를 위한 향상된 보기를 통해 추가 비용 최소화를 이끌어 냅니다.

필수 조건

• 기존 Azure Cosmos DB 계정.
  • 기존 Azure 구독이 있는 경우 새 계정을 만듭니다.
  • Azure 구독이 없는 경우 시작하기 전에 체험 계정을 만듭니다.
  • 또는 커밋하기 전에 Azure Cosmos DB 평가판을 사용해 볼 수 있습니다.

진단 설정 만들기

여기서는 계정에 대한 진단 설정을 만드는 프로세스를 안내합니다.

Azure Portal

1. Azure Portal에 로그인합니다.

2. Azure Cosmos DB 계정으로 이동합니다. 모니터링 섹션 아래에서 진단 설정 창을 열고 진단 설정 추가 옵션을 선택합니다.

   

   Important

   전체 텍스트 쿼리 기능이 계정에서 사용하도록 설정되지 않은 경우 “전체 텍스트 쿼리를 사용하도록 설정[...]”이라는 메시지가 표시될 수 있습니다. 이 기능을 사용하지 않으려면 이 경고를 무시해도 됩니다. 자세한 내용은 전체 텍스트 쿼리 사용을 참조하세요.

3. 진단 설정 창에서 원하는 범주로 양식을 채웁니다. 여기에 로그 범주 목록이 포함됩니다.

   범주	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	이 표에서는 NoSQL용 API 계정에 대해 실행되는 쿼리 작업을 자세히 설명합니다. 기본값으로, 쿼리 텍스트와 해당 매개 변수는 요청에 의해 사용할 수 있는 전체 텍스트 쿼리 로깅으로 개인 데이터를 로깅하지 않도록 난독 처리됩니다.	databasename, partitionkeyrangeid, querytext
   PartitionKeyStatistics	모든 API	파티션 키의 예상 스토리지 크기(KB)를 표시하여 논리 파티션 키의 통계를 기록합니다. 이 표는 스토리지 기울이기 문제 해결에 유용합니다. 이 PartitionKeyStatistics 로그는 다음 조건이 충족되는 경우에만 내보내집니다. 1. 물리적 파티션의 문서의 1% 이상에 동일한 논리적 파티션 키가 있습니다. 2. PartitionKeyStatistics 로그는 물리적 파티션의 모든 키 중에서 가장 큰 스토리지 크기를 가진 상위 3개의 키를 캡처합니다. 이전 조건이 충족되지 않으면, 파티션 키 통계 데이터를 사용할 수 없습니다. 위의 조건이 계정에 대해 충족되지 않아도 괜찮습니다. 이는 일반적으로 논리 파티션 스토리지 기울이기가 없음을 의미합니다. 참고: 파티션 키의 예상 크기는 물리적 파티션의 문서가 거의 같은 크기라고 가정하는 샘플링 접근 방식을 사용하여 계산됩니다. 문서 크기가 물리적 파티션에서 균일하지 않으면 예상 파티션 키 크기가 정확하지 않을 수 있습니다.	subscriptionId, regionName, partitionKey, sizeKB
   PartitionKeyRUConsumption	API for NoSQL 또는 API for Apache Gremlin	파티션 키의 집계된 초당 RU/s 소비를 로그합니다. 이 표는 핫 파티션 문제 해결에 유용합니다. 현재 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

4. 범주 세부 정보를 선택한 후, 원하는 대상으로 로그를 보냅니다. Log Analytics 작업 영역에 로그를 보내는 경우, 대상 테이블로 특정 리소스를 선택해야 합니다.

   

Azure CLI

az monitor diagnostic-settings create 명령을 사용하여 Azure CLI를 통해 진단 설정을 만듭니다. 매개 변수에 대한 설명은 이 명령에 대한 설명서를 참조하세요.

참고 항목

NoSQL용 API를 사용하는 경우 export-to-resource-specific 속성을 true로 설정하는 것이 좋습니다.

1. 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>"
   

2. 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"
   

REST API

대화형 콘솔을 통해 진단 설정을 만드는 데 Azure Monitor REST API를 사용합니다.

참고 항목

리소스별 테이블을 사용하도록 설정하기 위해 logAnalyticsDestinationType 속성을 Dedicated로 설정하는 것이 좋습니다.

1. HTTP PUT 요청을 만듭니다.

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

2. 이 헤더는 요청과 함께 사용합니다.

   매개 변수/헤더	값/설명
   이름	진단 설정의 이름입니다.
   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 구문을 참조하세요.

3. 요청 본문을 이 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
   }
   

ARM 템플릿

여기서는 ARM(Azure Resource Manager) 템플릿을 사용하여 진단 설정을 만듭니다.

참고 항목

logAnalyticsDestinationType 속성을 Dedicated로 설정하여 리소스별 테이블을 사용하도록 설정합니다.

1. 다음 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"
             }
           ]
         }
       }
     ]
   }
   

2. 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"
       }
     }
   }
   

3. 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 Monitor 가격을 참조하세요. 문제 해결 후 이 기능을 사용하지 않도록 설정하는 것이 좋습니다.

Azure Cosmos DB는 자세한 문제 해결을 위한 고급 로깅을 제공합니다. 전체 텍스트 쿼리를 사용하도록 설정하면, Azure Cosmos DB 계정 내의 모든 요청에 대해 난독 분석된 쿼리를 볼 수 있습니다. 또한 Azure Cosmos DB가 로그에 이 데이터에 액세스하고 이 데이터를 표면화할 수 있는 권한을 부여합니다.

Azure Portal

1. 이 기능을 사용하도록 설정하려면 Azure Cosmos DB 계정의 Features 페이지로 이동합니다.

   

2. Enable를 선택합니다. 이 설정은 몇 분 내에 적용됩니다. 새로 검색된 모든 로그에는 각 요청에 대한 전체 텍스트 또는 PIICommand 텍스트가 있습니다.

   

Azure CLI / REST API / ARM 템플릿

1. Azure CLI에 로그인했는지 확인합니다. 자세한 내용은 Azure CLI로 로그인을 참조하세요. 필요에 따라 CLI에 대한 활성 구독을 구성했는지 확인합니다. 자세한 내용은 활성 Azure CLI 구독 변경을 참조하세요.

2. accountName 및 resourceGroupName에 대한 셸 변수를 만듭니다.

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

3. 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
   )
   

4. 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"
     }
   }
   

5. 전체 텍스트 쿼리가 아직 사용하도록 설정되지 않은 경우 HTTP az rest 동사 및 JSON 페이로드와 함께 PATCH를 다시 사용하여 사용하도록 설정합니다.

   az rest \
       --method PATCH \
       --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
       --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
   

   참고 항목

   PowerShell 프롬프트 내에서 Azure CLI를 사용하는 경우 백슬래시(\) 문자를 사용하여 큰따옴표를 이스케이프해야 합니다.

6. 작업을 완료할 때까지 몇 분 정도 기다립니다. 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"
     }
   }
   

쿼리 데이터

새로 사용하도록 설정된 이 기능을 사용하여 쿼리하는 방법을 알아보려면 다음을 참조하세요.

• API for NoSQL
• MongoDB용 API
• Apache Cassandra용 API
• API for Apache Gremlin

다음 단계

Azure Cosmos DB 모니터링 데이터 참조