Monitorare i dati di Azure Cosmos DB usando le impostazioni di diagnostica di Log Analytics di Monitoraggio di Azure

SI APPLICA A: NoSQL MongoDB Cassandra Gremlin Tabella

Le impostazioni di diagnostica in Azure vengono usate per raccogliere i log delle risorse. Le risorse generano log delle risorse di Azure e forniscono dati completi e frequenti sul funzionamento di tale risorsa. Questi log vengono acquisiti su richiesta e sono detti anche log del piano dati. Alcuni esempi di operazioni del piano dati includono Delete, Insert e ReadFeed. Il contenuto di questi log varia in base al tipo di risorsa.

Per altre informazioni sulle impostazioni di diagnostica, vedere Impostazioni di diagnostica in Monitoraggio di Azure.

Nota

È consigliabile creare l'impostazione di diagnostica in modalità specifica della risorsa (per tutte le API ad eccezione dell'API per Tabella) seguendo le istruzioni riportate nella scheda API REST. Questa opzione offre ottimizzazioni aggiuntive dei costi con una visualizzazione migliorata per la gestione dei dati.

Prerequisiti

• Un account Azure Cosmos DB esistente.
  • Se si dispone di una sottoscrizione di Azure, creare un nuovo account.
  • Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
  • In alternativa, è possibile provare Azure Cosmos DB gratuitamente prima di eseguire il commit.
• Area di lavoro Log Analytics di Monitoraggio di Azure esistente.

Avviso

Se è necessario eliminare, rinominare o spostare una risorsa oppure eseguirne la migrazione tra gruppi di risorse o sottoscrizioni, eliminare innanzitutto le impostazioni di diagnostica. In caso contrario, se si ricrea questa risorsa, le impostazioni di diagnostica della risorsa eliminata potrebbero essere incluse nella nuova risorsa, a seconda della configurazione di ciascuna. Se le impostazioni di diagnostica sono incluse nella nuova risorsa, viene ripresa la raccolta dei log delle risorse come definita nell'impostazione di diagnostica e i dati delle metriche e dei log applicabili alla destinazione configurata in precedenza.

Inoltre, è consigliabile eliminare le impostazioni di diagnostica per una risorsa che si intende eliminare e non pianificarne di nuovo l'uso per mantenere pulito l'ambiente.

Creare impostazioni di diagnostica

In questa sezione viene illustrato il processo di creazione delle impostazioni di diagnostica per l'account.

Nota

La metrica per l'esportazione dei log come categoria non è al momento supportata.

Azure portal

1. Accedere al portale di Azure.

2. Passare all'account Azure Cosmos DB esistente.

3. Nella sezione Monitoraggio del menu delle risorse selezionare Impostazioni di diagnostica. Selezionare quindi l'opzione Aggiungi impostazione di diagnostica.

   

   Importante

   Potrebbe essere visualizzato un prompt che chiede di "abilitare la query full-text [...] per la registrazione più dettagliata" se la funzionalità query full-text non è abilitata nell'account. È possibile ignorare questo avviso in modo sicuro se non si desidera abilitare questa funzionalità. Per altre informazioni, vedere Abilitare la query full-text.

4. Nel riquadro Impostazioni di diagnostica, denominare l'impostazione example-setting e quindi selezionare la categoria QueryRuntimeStatistics. Abilitare la casella di controllo Invia al log Analitica'area di lavoro, selezionando l'area di lavoro esistente. Infine, selezionare Specifico della risorsa come opzione di destinazione.

   

Interfaccia della riga di comando di Azure

Usare il comando az monitor diagnostic-settings create per creare un'impostazione di diagnostica con l'interfaccia della riga di comando di Azure. Vedere la documentazione per questo comando per le descrizioni dei relativi parametri.

1. Assicurarsi di aver eseguito l'accesso all'interfaccia della riga di comando di Azure. Per altre informazioni, vedere Accedere tramite l'interfaccia della riga di comando di Azure.

2. Usare az monitor diagnostic-settings create per creare l'impostazione.

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

   Importante

   In questo esempio viene usato l'argomento --export-to-resource-specific per abilitare tabelle specifiche delle risorse.

3. Esaminare i risultati della creazione della nuova impostazione usando 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

Usare l'API REST di Monitoraggio di Azure per creare un'impostazione di diagnostica tramite la console interattiva.

1. Assicurarsi di aver eseguito l'accesso all'interfaccia della riga di comando di Azure. Per altre informazioni, vedere Accedere tramite l'interfaccia della riga di comando di Azure.

2. Creare l'impostazione di diagnostica per la risorsa di Azure Cosmos DB usando una richiesta HTTP PUT e 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"
       }
     }'
   

   Importante

   Questo esempio imposta la proprietà logAnalyticsDestinationType su Dedicated per abilitare tabelle specifiche delle risorse.

3. Usare di nuovo az rest con un verbo GET HTTP per ottenere le proprietà dell'impostazione di diagnostica.

   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

Usare un modello Bicep per creare l'impostazione di diagnostica.

1. Assicurarsi di aver eseguito l'accesso all'interfaccia della riga di comando di Azure. Per altre informazioni, vedere Accedere tramite l'interfaccia della riga di comando di Azure.

2. Creare un file denominato diagnosticSetting.bicep.

3. Immettere il contenuto del modello Bicep seguente che distribuisce l'impostazione di diagnostica per la risorsa di Azure Cosmos DB.

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

   Importante

   Questo esempio imposta la proprietà logAnalyticsDestinationType su Dedicated per abilitare tabelle specifiche delle risorse.

4. Distribuire il modello usando 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>"
   

   Suggerimento

   Usare il comando az bicep build per convertire il modello Bicep in un modello di Azure Resource Manager.

Modello ARM

Usare un modello di Azure Resource Manager per creare l'impostazione di diagnostica.

1. Assicurarsi di aver eseguito l'accesso all'interfaccia della riga di comando di Azure. Per altre informazioni, vedere Accedere tramite l'interfaccia della riga di comando di Azure.

2. Creare un file denominato diagnosticSetting.bicep.

3. Immettere il contenuto del modello di Resource Manager seguente che distribuisce l'impostazione di diagnostica per la risorsa di Azure Cosmos DB.

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

   Importante

   Questo esempio imposta la proprietà logAnalyticsDestinationType su Dedicated per abilitare tabelle specifiche delle risorse.

4. Distribuire il modello usando 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>"
   

   Suggerimento

   Usare il comando az bicep decompile per convertire il modello di Azure Resource Manager in un modello Bicep.

Abilitare la query full-text per la registrazione del testo della query

Azure Cosmos DB offre la registrazione avanzata per la risoluzione dei problemi dettagliata. Abilitando la query full-text, sarà possibile visualizzare la query completa per tutte le richieste all'interno dell'account Azure Cosmos DB. Si concederà anche l'autorizzazione ad Azure Cosmos DB di accedere e visualizzare questi dati nei log.

Avviso

L'abilitazione di questa funzionalità può comportare costi di registrazione aggiuntivi. Per informazioni dettagliate sui prezzi, consultare Prezzi di Monitoraggio di Azure. È consigliabile disabilitare questa funzionalità dopo la risoluzione dei problemi.

Azure portal

1. Nella pagina dell'account Azure Cosmos DB esistente, selezionare l'opzione Funzionalità nella sezione Impostazioni del menu delle risorse. Selezionare quindi la funzionalità Query full-text di diagnostica.

   

2. Nella finestra di dialogo, selezionare Enable. Questa impostazione viene applicata entro pochi minuti. Tutti i log appena inseriti hanno il testo full-text o PIICommand per ogni richiesta.

   

Interfaccia della riga di comando di Azure / API REST / Bicep / modello di ARM

Usare l'interfaccia della riga di comando di Azure per abilitare query full-text per l'account Azure Cosmos DB.

1. Abilitare la query full-text usando di nuovo az rest con un verbo PATCH HTTP e un payload JSON.

   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. Attendere alcuni minuti per il completamento dell'operazione. Controllare lo stato della query full-text usando di nuovo az rest con HTTP GET.

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

   L'output dovrebbe essere simile a questo esempio.

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

Contenuto correlato

• Query di diagnostica nell'API per NoSQL
• Query di diagnostica nell'API per MongoDB
• Query di diagnostica nell'API per Apache Cassandra