Überwachen von Azure Cosmos DB-Daten mithilfe von Log Analytics-Diagnoseeinstellungen in Azure Monitor

GILT FÜR: NoSQL MongoDB Cassandra Gremlin Tabelle

Diagnoseeinstellungen in Azure werden zum Sammeln von Ressourcenprotokollen verwendet. Ressourcen geben Azure-Ressourcenprotokolle aus und liefern umfangreiche und regelmäßige Daten über den Betrieb der jeweiligen Ressource. Diese Protokolle werden pro Anforderung erfasst und werden auch als Datenebenenprotokolle bezeichnet. Einige Beispiele für Datenebenenvorgänge sind „delete“, „insert“ und „readFeed“. Der Inhalt dieser Protokolle variiert je nach Ressourcentyp.

Weitere Informationen zu Diagnoseeinstellungen finden Sie unter Diagnoseeinstellungen in Azure Monitor.

Hinweis

Sie sollten die Diagnoseeinstellung (für alle APIs außer der API für Table) im ressourcenspezifischen Modus erstellen. Befolgen Sie dazu die Anweisungen in der Registerkarte REST-API. Diese Option bietet zusätzliche Kostenoptimierungen mit einer verbesserten Ansicht für die Verarbeitung von Daten.

Voraussetzungen

• Ein vorhandenes Azure Cosmos DB-Konto
  • Falls Sie bereits über ein Azure-Abonnement verfügen, erstellen Sie ein neues Konto.
  • Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
  • Alternativ können Sie Azure Cosmos DB kostenlos testen, bevor Sie sich festlegen.
• Ein vorhandener Log Analytics-Arbeitsbereich in Azure Monitor

Warnung

Wenn Sie eine Ressource löschen, umbenennen, verschieben oder über Ressourcengruppen oder Abonnements hinweg migrieren möchten, löschen Sie zunächst die Diagnoseeinstellungen. Andernfalls kann es abhängig von der Ressourcenkonfiguration der jeweiligen Ressource vorkommen, dass die Diagnoseeinstellungen für die gelöschte Ressource in die neue Ressource eingeschlossen werden, wenn Sie diese Ressource neu erstellen. Wenn die Diagnoseeinstellungen in die neue Ressource eingeschlossen werden, wird die Sammlung von Ressourcenprotokollen wie in der Diagnoseeinstellung definiert fortgesetzt, und die entsprechenden Metrik- und Protokolldaten werden an das zuvor konfigurierte Ziel gesendet.

Außerdem empfiehlt es sich, die Diagnoseeinstellungen für eine Ressource, die Sie löschen und voraussichtlich nicht erneut verwenden möchten, zu löschen, um die Umgebung zu bereinigen.

Erstellen von Diagnoseeinstellungen

Hier erfahren Sie mehr über den Prozess Diagnoseeinstellungen für Ihr Konto zu erstellen.

Hinweis

Die Metrik zum Protokollexport als Kategorie wird derzeit nicht unterstützt.

Azure portal

1. Melden Sie sich beim Azure-Portal an.

2. Navigieren Sie zu Ihrem vorhandenen Azure Cosmos DB-Konto.

3. Wählen Sie im Ressourcenmenü im Abschnitt Überwachung die Option Diagnoseeinstellungen aus. Wählen Sie dann die Option Diagnoseeinstellung hinzufügen aus.

   

   Wichtig

   Möglicherweise wird die Eingabeaufforderung „Volltextabfrage [...] zur detaillierteren Protokollierung aktivieren“ angezeigt, wenn die Funktion Volltextabfrage in Ihrem Konto nicht aktiviert ist. Sie können diese Warnung bedenkenlos ignorieren, wenn Sie diese Funktion nicht aktivieren möchten. Weitere Informationen finden Sie unter Aktivieren der Volltextabfrage.

4. Benennen Sie im Bereich Diagnoseeinstellungen die Einstellung example-setting, und wählen Sie dann die Kategorie QueryRuntimeStatistics aus. Aktivieren Sie das Kontrollkästchen An einen Log Analytics-Arbeitsbereich senden, und wählen Sie Ihren vorhandenen Arbeitsbereich aus. Wählen Sie schließlich Ressourcenspezifisch als Zieloption aus.

   

Azure-Befehlszeilenschnittstelle

Verwenden Sie den Befehl az monitor diagnostic-settings create, um eine Diagnoseeinstellung mit der Azure CLI zu erstellen. Beschreibungen der zugehörigen Parameter finden Sie in der Dokumentation zu diesem Befehl.

1. Vergewissern Sie sich, dass Sie bei der Azure CLI angemeldet sind. Weitere Informationen finden Sie unter Anmelden mit der Azure CLI.

2. Verwenden Sie az monitor diagnostic-settings create, um die Einstellung zu erstellen.

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

   Wichtig

   In diesem Beispiel wird das Argument --export-to-resource-specific verwendet, um ressourcenspezifische Tabellen zu aktivieren.

3. Überprüfen Sie die Ergebnisse des Erstellens Ihrer neuen Einstellung mithilfe von 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" \
     )
   

REST-API

Verwenden Sie die Azure Monitor-REST-API, um eine Diagnoseeinstellung über die interaktive Konsole zu erstellen.

1. Vergewissern Sie sich, dass Sie bei der Azure CLI angemeldet sind. Weitere Informationen finden Sie unter Anmelden mit der Azure CLI.

2. Erstellen Sie die Diagnoseeinstellung für Ihre Azure Cosmos DB-Ressource mithilfe einer HTTP-Anforderung PUT sowie az rest.

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

   Wichtig

   In diesem Beispiel wird die logAnalyticsDestinationType-Eigenschaft auf Dedicated festgelegt, um ressourcenspezifische Tabellen zu aktivieren.

3. Verwenden Sie az rest erneut mit einem HTTP-Verb GET, um die Eigenschaften der Diagnoseeinstellung abzurufen.

   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

Verwenden Sie eine Bicep-Vorlage, um die Diagnoseeinstellung zu erstellen.

1. Vergewissern Sie sich, dass Sie bei der Azure CLI angemeldet sind. Weitere Informationen finden Sie unter Anmelden mit der Azure CLI.

2. Erstelle eine neue Datei mit dem Namen diagnosticSetting.bicep.

3. Geben Sie den folgenden Bicep-Vorlageninhalt ein, der die Diagnoseeinstellung für Ihre Azure Cosmos DB-Ressource bereitstellt.

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

   Wichtig

   In diesem Beispiel wird die logAnalyticsDestinationType-Eigenschaft auf Dedicated festgelegt, um ressourcenspezifische Tabellen zu aktivieren.

4. Bereitstellen der Vorlage mithilfe von 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>"
   

   Tipp

   Verwenden Sie den Befehl az bicep build, um die Bicep-Vorlage in eine Azure Resource Manager-Vorlage zu konvertieren.

ARM-Vorlage

Verwenden Sie eine Azure Resource Manager-Vorlage zum Erstellen der Diagnoseeinstellung.

1. Vergewissern Sie sich, dass Sie bei der Azure CLI angemeldet sind. Weitere Informationen finden Sie unter Anmelden mit der Azure CLI.

2. Erstelle eine neue Datei mit dem Namen diagnosticSetting.bicep.

3. Geben Sie den folgenden Azure Resource Manager-Vorlageninhalt ein, der die Diagnoseeinstellung für Ihre Azure Cosmos DB-Ressource bereitstellt.

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

   Wichtig

   In diesem Beispiel wird die logAnalyticsDestinationType-Eigenschaft auf Dedicated festgelegt, um ressourcenspezifische Tabellen zu aktivieren.

4. Bereitstellen der Vorlage mithilfe von 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>"
   

   Tipp

   Verwenden Sie den Befehl az bicep decompile, um die Azure Resource Manager-Vorlage in eine Bicep-Vorlage zu konvertieren.

Aktivieren der Volltextabfrage zur Protokollierung von Abfragetext

Azure Cosmos DB bietet erweiterte Protokollierung für eine detaillierte Problembehandlung. Wenn Sie die Volltextabfrage aktivieren, können Sie die entschleierte Abfrage für alle Anforderungen in Ihrem Azure Cosmos DB-Konto anzeigen. Außerdem erteilen Sie Azure Cosmos DB die Erlaubnis, auf diese Daten zuzugreifen und sie in Ihren Protokollen anzuzeigen.

Warnung

Die Aktivierung dieses Features kann zu zusätzlichen Protokollierungskosten führen. Preisinformationen finden Sie unter Azure Monitor Preise. Sie sollten dieses Feature nach der Problembehandlung deaktivieren.

Azure portal

1. Wählen Sie auf der vorhandenen Azure Cosmos DB-Kontoseite die Option Features im Abschnitt Einstellungen des Ressourcenmenüs aus. Wählen Sie dann das Feature Diagnose-Volltextabfrage aus.

   

2. Wählen Sie im Dialogfeld Enable aus. Diese Einstellung wird innerhalb weniger Minuten angewendet. Alle neu erfassten Protokolle enthalten den Volltext oder den PIICommand-Text für alle Anforderungen.

   

Azure CLI/REST-API/Bicep/ARM-Vorlage

Verwenden Sie die Azure CLI, um Volltextabfragen für Ihr Azure Cosmos DB-Konto zu aktivieren.

1. Aktivieren Sie Volltextabfragen mithilfe von az rest erneut. Nutzen Sie dazu ein HTTP-Verb PATCH und eine JSON-Payload.

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

2. Warten Sie einige Minuten, bis der Vorgang abgeschlossen ist. Überprüfen Sie den Status der Volltextabfrage, indem Sie az rest erneut mit HTTP-GET verwenden.

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

   Die Ausgabe sollte dem folgenden Beispiel ähneln.

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

Zugehöriger Inhalt

• Diagnoseabfragen in der API für NoSQL
• Diagnoseabfragen in der API für MongoDB
• Diagnoseabfragen in der API für Apache Cassandra