Azure Monitor Log Analytics 진단 설정을 사용하여 Azure Cosmos DB 데이터 모니터링

아티클
08/15/2024

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

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

진단 설정에 대해 자세히 알아보려면 Azure Monitor의 진단 설정을 참조하세요.

참고 항목

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

필수 조건

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

Warning

리소스를 삭제, 변경, 이동하거나 리소스 그룹 또는 구독 간에 마이그레이션해야 하는 경우 먼저 해당 진단 설정을 삭제합니다. 그렇지 않으면 이 리소스를 다시 만들 때 삭제된 리소스에 대한 진단 설정이 각 리소스의 리소스 구성에 따라 새 리소스에 포함될 수 있습니다. 진단 설정이 새 리소스에 포함된 경우 진단 설정에 정의된 대로 리소스 로그 컬렉션을 다시 시작하고 해당 메트릭 및 로그 데이터를 이전에 구성된 대상으로 보냅니다.

또한 삭제할 리소스에 대한 진단 설정은 삭제하고 환경을 깨끗하게 유지하기 위해 다시 사용하지 않는 것이 좋습니다.

진단 설정 만들기

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

참고 항목

로그를 범주로 내보내는 메트릭은 현재 지원되지 않습니다.

Azure Portal에 로그인합니다.
기존 Azure Cosmos DB 계정으로 이동합니다.
리소스 메뉴의 모니터링 섹션에서 진단 설정을 선택합니다. 그런 다음 진단 설정 추가 옵션을 선택합니다.

Important

전체 텍스트 쿼리 기능이 계정에서 사용하도록 설정되지 않은 경우 “전체 텍스트 쿼리를 사용하도록 설정[...]”이라는 메시지가 표시될 수 있습니다. 이 기능을 사용하지 않으려면 이 경고를 무시해도 됩니다. 자세한 내용은 전체 텍스트 쿼리 사용을 참조하세요.
진단 설정 창에서 설정 이름을 example-setting으로 지정한 다음 QueryRuntimeStatistics 범주를 선택합니다. Log Analytics 작업 영역으로 보내기 확인란을 사용하도록 설정하고 기존 작업 영역을 선택합니다. 마지막으로 대상 옵션으로 특정 리소스를 선택합니다.

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

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
    }
  ]'

Important

이 샘플은 --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"
    }
  }'

Important

이 샘플은 특정 리소스 테이블을 사용하도록 설정하기 위해 logAnalyticsDestinationType 속성을 Dedicated로 설정합니다.

진단 설정의 속성을 가져오려면 HTTP GET 동사와 함께 az rest를 다시 사용합니다.

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
      }
    ]
  }
}

Important

이 샘플은 특정 리소스 테이블을 사용하도록 설정하기 위해 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 Resource Manager 템플릿으로 변환합니다.

Azure Resource Manager 템플릿을 사용하여 진단 설정을 만듭니다.

Azure CLI에 로그인했는지 확인합니다. 자세한 내용은 Azure CLI로 로그인을 참조하세요.
이름이 diagnosticSetting.bicep인 새 파일을 만듭니다.

Azure Cosmos DB 리소스에 대한 진단 설정을 배포하는 다음 Azure Resource Manager 템플릿 콘텐츠를 입력합니다.

{
  "$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
          }
        ]
      }
    }
  ]
}

Important

이 샘플은 특정 리소스 테이블을 사용하도록 설정하기 위해 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 Resource Manager 템플릿을 Bicep 템플릿으로 변환합니다.

쿼리 텍스트 로깅에 전체 텍스트 쿼리 사용

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

Warning

이 기능을 사용하도록 설정하면 추가 로깅 비용이 발생할 수 있습니다. 가격 세부 정보는 Azure Monitor 가격을 참조하세요. 문제 해결 후 이 기능을 사용하지 않도록 설정하는 것이 좋습니다.

Azure Portal
Azure CLI/REST API/Bicep/ARM 템플릿

기존 Azure Cosmos DB 계정 페이지에서 리소스 메뉴의 설정 섹션에 있는 기능 옵션을 선택합니다. 그런 다음 진단 전체 텍스트 쿼리 기능을 선택합니다.
대화 상자에서 Enable을 선택합니다. 이 설정은 몇 분 내에 적용됩니다. 이제 새로 검색된 모든 로그에는 각 요청에 대한 전체 텍스트 또는 PIICommand 텍스트가 있습니다.

Azure CLI를 사용하여 Azure Cosmos DB 계정에 대한 전체 텍스트 쿼리를 사용하도록 설정합니다.

HTTP PATCH 동사 및 JSON 페이로드와 함께 az rest를 다시 사용하여 전체 텍스트 쿼리를 사용하도록 설정합니다.

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"
      }
    }
  }'

작업을 완료할 때까지 몇 분 정도 기다립니다. HTTP GET과 함께 az rest를 다시 사용하여 전체 텍스트 쿼리 상태를 확인합니다.

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 데이터 모니터링

필수 조건

진단 설정 만들기

쿼리 텍스트 로깅에 전체 텍스트 쿼리 사용

피드백

추가 리소스

다음을 통해 공유

Azure Monitor Log Analytics 진단 설정을 사용하여 Azure Cosmos DB 데이터 모니터링

필수 조건

진단 설정 만들기

쿼리 텍스트 로깅에 전체 텍스트 쿼리 사용

관련 콘텐츠

피드백

추가 리소스