Monitorare i dati di Azure Cosmos DB usando le impostazioni di diagnostica in Azure

Articolo
03/25/2024

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.

Le metriche della piattaforma e il log attività vengono raccolti automaticamente, ma è necessario creare un'impostazione di diagnostica per raccogliere i log delle risorse o per inviarli all'esterno di Monitoraggio di Azure. È possibile attivare l'impostazione di diagnostica per gli account Azure Cosmos DB e inviare i log delle risorse alle origini seguenti:

Aree di lavoro di Log Analytics
- I dati inviati a Log Analytics possono essere scritti in Diagnostica di Azure (legacy) o Tabelle specifiche delle risorse (anteprima)
Hub eventi
Account di archiviazione

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 per la creazione dell'impostazione di diagnostica tramite l'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 ha 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.

Creare impostazioni di diagnostica

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

Accedere al portale di Azure.
Accedere all'account Azure Cosmos DB. Aprire il riquadro Impostazioni di diagnostica nella sezione Monitoraggio e quindi selezionare 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.

Nel riquadro Impostazioni di diagnostica compilare il modulo con le categorie preferite. Di seguito è riportato un elenco di categorie di log.

Categoria	API	Definizione	Proprietà chiave
DataPlaneRequests	Consigliato per l'API per NoSQL	Registra le richieste back-end come operazioni del piano dati che vengono richieste eseguite per creare, aggiornare, eliminare o recuperare dati all'interno dell'account.	`Requestcharge`, `statusCode`, `clientIPaddress`, `partitionID`, `resourceTokenPermissionIdresourceTokenPermissionMode`
MongoRequests	API per MongoDB	Registra le richieste avviate dall'utente dal front-end per gestire le richieste ad Azure Cosmos DB for MongoDB. Quando si abilita questa categoria, assicurarsi di disabilitare DataPlaneRequests.	`Requestcharge`, `opCode`, `retryCount`, `piiCommandText`
CassandraRequests	API per Apache Cassandra	Registra le richieste avviate dall'utente dal front-end per gestire le richieste ad Azure Cosmos DB for Cassandra.	`operationName`, `requestCharge`, `piiCommandText`
GremlinRequests	API per Apache Gremlin	Registra le richieste avviate dall'utente dal front-end per gestire le richieste ad Azure Cosmos DB for Gremlin.	`operationName`, `requestCharge`, `piiCommandText`, `retriedDueToRateLimiting`
QueryRuntimeStatistics	API per NoSQL	Questa tabella descrive in dettaglio le operazioni di query eseguite su un account API per NoSQL. Per impostazione predefinita, il testo della query e i relativi parametri vengono offuscati per evitare di registrare i dati personali con la registrazione di query full-text disponibile per richiesta.	`databasename`, `partitionkeyrangeid`, `querytext`
PartitionKeyStatistics	Tutte le API	Registra le statistiche delle chiavi di partizione logiche rappresentando le dimensioni di archiviazione stimate (KB) delle chiavi. Questa tabella è utile per la risoluzione dei problemi di asimmetria dell'archiviazione. Questo log PartitionKeyStatistics viene generato solo se le condizioni seguenti sono vere: 1. Almeno l'1% dei documenti nella partizione fisica ha la stessa chiave di partizione logica. 2. Tra tutte le chiavi nella partizione fisica, il log PartitionKeyStatistics acquisisce le prime tre chiavi con dimensioni di archiviazione maggiori. Se le condizioni precedenti non vengono soddisfatte, i dati delle statistiche della chiave di partizione non sono disponibili. Non ci sono problemi se le condizioni precedenti non vengono soddisfatte per l'account, solitamente ciò indica che non sono presenti differenze di archiviazione della partizione logica. Nota: le dimensioni stimate delle chiavi di partizione vengono calcolate usando un approccio di campionamento che presuppone che i documenti nella partizione fisica siano approssimativamente delle stesse dimensioni. Se le dimensioni del documento non sono uniformi nella partizione fisica, le dimensioni stimate della chiave di partizione potrebbero non essere accurate.	`subscriptionId`, `regionName`, `partitionKey`, `sizeKB`
PartitionKeyRUConsumption	API per NoSQL o API per Apache Gremlin	Registra il consumo aggregato di UR/sec delle chiavi di partizione. Questa tabella è utile per la risoluzione dei problemi relativi alle partizioni ad accesso frequente. Attualmente, Azure Cosmos DB segnala le chiavi di partizione solo per gli account Api per NoSQL e per operazioni di lettura/scrittura, query e stored procedure punto.	`subscriptionId`, `regionName`, `partitionKey`, `requestCharge`, `partitionKeyRangeId`
ControlPlaneRequests	Tutte le API	Registra i dettagli sulle operazioni del piano di controllo, che include la creazione di un account, l'aggiunta o la rimozione di un'area, l'aggiornamento delle impostazioni di replica dell'account e così via.	`operationName`, `httpstatusCode`, `httpMethod`, `region`
TableApiRequests	API per Table	Registra le richieste avviate dall'utente dal front-end per gestire le richieste ad Azure Cosmos DB for Table.	`operationName`, `requestCharge`, `piiCommandText`

Dopo aver selezionato i Dettagli categorie, inviare i log alla destinazione preferita. Se si inviano log a un'area di lavoro Log Analytics, assicurarsi di selezionare Specifica della risorsa come Tabella destinazione.

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.

Nota

Se si usa l'API per NoSQL, è consigliabile impostare la proprietà export-to-resource-specific su true.

Creare variabili della shell per subscriptionId, diagnosticSettingName, workspaceName e 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>"

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

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"

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

Nota

È consigliabile impostare la proprietà logAnalyticsDestinationType su Dedicata per abilitare tabelle specifiche delle risorse.

Creare una richiesta PUT HTTP.

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

Usare queste intestazioni con la richiesta.

Parametri/intestazioni	Valore/Descrizione
name	Nome dell'impostazione di diagnostica.
resourceUri	URI di sottorisorsa di Microsoft Insights per l'account Azure Cosmos DB.
api-version	`2017-05-01-preview`
Content-Type	`application/json`

Nota

L'URI per la sottorisorsa di Microsoft Insights è in questo formato: subscriptions/{SUBSCRIPTION_ID}/resourceGroups/{RESOURCE_GROUP}/providers/Microsoft.DocumentDb/databaseAccounts/{ACCOUNT_NAME}/providers/microsoft.insights/diagnosticSettings/{DIAGNOSTIC_SETTING_NAME}. Per altre informazioni sugli URI delle risorse di Azure Cosmos DB, vedere sintassi dell'URI delle risorse per l'API REST di Azure Cosmos DB.

Impostare il corpo della richiesta su questo payload 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
}

In questo caso, usare un modello di Azure Resource Manager (ARM) per creare un'impostazione di diagnostica.

Nota

Impostare la proprietà logAnalyticsDestinationType su Dedicato per abilitare tabelle specifiche delle risorse.

Creare il file di modello JSON seguente per distribuire le impostazioni 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": {
    "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"
          }
        ]
      }
    }
  ]
}

Creare il file di parametri JSON seguente con le impostazioni appropriate per la risorsa di Azure Cosmos DB.

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

Distribuire il modello usando az deployment group create.

az deployment group create \
    --resource-group <resource-group-name> \
    --template-file <path-to-template>.json \
    --parameters @<parameters-file-name>.json

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

Nota

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

Azure portal
Interfaccia della riga di comando di Azure/API REST/modello di Resource Manager

Per abilitare questa funzionalità, passare alla pagina Features nell'account Azure Cosmos DB.
Selezionare Enable. Questa impostazione viene applicata entro pochi minuti. Tutti i log appena inseriti hanno il testo full-text o PIICommand per ogni richiesta.

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. Facoltativamente, assicurarsi di aver configurato la sottoscrizione attiva per l'interfaccia della riga di comando. Per altre informazioni, vedere Modificare la sottoscrizione attiva dell'interfaccia della riga di comando di Azure.

Creare variabili della shell per accountName e resourceGroupName.

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

# Variable for account name
accountName="<account-name>"

Ottenere l'identificatore univoco per l'account esistente usando az show.

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query id

Archiviare l'identificatore univoco in una variabile della shell denominata $uri.

uri=$(
    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $accountName \
        --query id \
        --output tsv
)

Eseguire una query sulla risorsa usando l'API REST e az rest con un verbo HTTP GET per verificare se la query full-text è già abilitata.

az rest \
    --method GET \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --query "{accountName:name,fullTextQuery:{state:properties.diagnosticLogSettings.enableFullTextQuery}}"

Se la query full-text non è abilitata, l'output sarà simile a questo esempio.

{
  "accountName": "<account-name>",
  "fullTextQuery": {
    "state": "None"
  }
}

Se la query full-text non è già abilitata, abilitarla usando di nuovo az rest con un verbo HTTP PATCH e un payload JSON.
```
az rest \
    --method PATCH \
    --uri "https://management.azure.com/$uri/?api-version=2021-05-01-preview" \
    --body '{"properties": {"diagnosticLogSettings": {"enableFullTextQuery": "True"}}}'
```
Nota

Se si usa l'interfaccia della riga di comando di Azure all'interno di un prompt di PowerShell, sarà necessario eseguire l'escape delle virgolette doppie usando un carattere barra rovesciata (\).

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

L'output dovrebbe essere simile a questo esempio.

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

Eseguire query sui dati

Per informazioni su come eseguire query usando queste funzionalità appena abilitate, vedere:

Passaggi successivi

Informazioni di riferimento sul monitoraggio dei dati di Azure Cosmos DB

Monitorare i dati di Azure Cosmos DB usando le impostazioni di diagnostica in Azure

Prerequisiti

Creare impostazioni di diagnostica

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

Eseguire query sui dati

Passaggi successivi

Risorse aggiuntive