Come controllare le operazioni del piano di controllo di Azure Cosmos DB

Articolo
03/28/2024

SI APPLICA A: NoSQL MongoDB Cassandra Gremlin Tabella

Il piano di controllo in Azure Cosmos DB è un servizio RESTful che consente di eseguire un set diversificato di operazioni nell'account Azure Cosmos DB. Espone un modello di risorse pubblico (ad esempio, database, account) e varie operazioni agli utenti finali per eseguire azioni sul modello di risorse. Le operazioni del piano di controllo includono modifiche all'account o al contenitore di Azure Cosmos DB. Ad esempio, le operazioni come la creazione di un account Azure Cosmos DB, l'aggiunta di un'area, l'aggiornamento della velocità effettiva, il failover dell'area, l'aggiunta di una rete virtuale e così via, sono alcune delle operazioni del piano di controllo. Questo articolo illustra come controllare le operazioni del piano di controllo in Azure Cosmos DB. È possibile eseguire le operazioni del piano di controllo sugli account Azure Cosmos DB usando l'interfaccia della riga di comando di Azure, PowerShell o il portale di Azure, mentre per i contenitori usare l'interfaccia della riga di comando di Azure o PowerShell.

Di seguito sono riportati alcuni scenari di esempio in cui le operazioni del piano di controllo di controllo sono utili:

Si vuole ricevere un avviso quando vengono modificate le regole del firewall per l'account Azure Cosmos DB. L'avviso è necessario per trovare modifiche non autorizzate alle regole che disciplinano la sicurezza di rete dell'account Azure Cosmos DB ed eseguire azioni rapide.
Si vuole ricevere un avviso se una nuova area viene aggiunta o rimossa dall'account Azure Cosmos DB. L'aggiunta o la rimozione di aree ha implicazioni sui requisiti di fatturazione e sovranità dei dati. Questo avviso consente di rilevare un'aggiunta o una rimozione accidentale dell'area nell'account.
Si vogliono ottenere altri dettagli dai log di diagnostica sulle modifiche apportate. Ad esempio, è stata modificata una rete virtuale.

Disabilitare l'accesso in scrittura ai metadati basati su chiave

Prima di controllare le operazioni del piano di controllo in Azure Cosmos DB, disabilitare l'accesso in scrittura ai metadati basati su chiave nell'account. Quando l'accesso in scrittura ai metadati basati su chiavi è disabilitato, i client che si connettono all'account Azure Cosmos DB tramite chiavi dell'account non possono accedere all'account. È possibile disabilitare l'accesso in scrittura impostando la proprietà disableKeyBasedMetadataWriteAccess su true. Dopo aver impostato questa proprietà, le modifiche a qualsiasi risorsa possono verificarsi da un utente con il ruolo e le credenziali di Azure appropriati. Per altre informazioni su come impostare questa proprietà, vedere l'articolo Impedire modifiche dagli SDK.

Dopo l'attivazione di disableKeyBasedMetadataWriteAccess, se i client basati su SDK eseguono operazioni di creazione o aggiornamento, viene restituito un errore "Operazione 'POST' sulla risorsa 'ContainerNameorDatabaseName' non consentita tramite l'endpoint di Azure Cosmos DB. È necessario attivare l'accesso a tali operazioni per l'account o eseguire le operazioni di creazione/aggiornamento tramite Azure Resource Manager, l'interfaccia della riga di comando di Azure o Azure PowerShell. Per tornare indietro, impostare disableKeyBasedMetadataWriteAccess su false usando l'interfaccia della riga di comando di Azure come descritto nell'articolo Impedire le modifiche da Azure Cosmos DB SDK. Assicurarsi di modificare il valore di disableKeyBasedMetadataWriteAccess in false anziché true.

Quando si disattiva l'accesso in scrittura ai metadati, tenere presente quanto segue:

Verificare e assicurarsi che le applicazioni non eseguano chiamate di metadati che modificano le risorse precedenti (ad esempio, creare una raccolta, aggiornare la velocità effettiva, …) usando l'SDK o le chiavi dell'account.
Quando disableKeyBasedMetadataWriteAccess è impostato su true, le operazioni sui metadati rilasciate dall'SDK vengono bloccate. In alternativa, è possibile usare il portale di Azure, l'interfaccia della riga di comando di Azure, Azure PowerShell o le distribuzioni di modelli di Azure Resource Manager per eseguire queste operazioni.

Abilitare i log di diagnostica per le operazioni del piano di controllo

È possibile abilitare i log di diagnostica per le operazioni del piano di controllo usando il portale di Azure. Dopo l'abilitazione, i log di diagnostica registreranno l'operazione come coppia di eventi di avvio e completamento con i dettagli pertinenti. Ad esempio, le proprietà RegionFailoverStart e RegionFailoverComplete completeranno l'evento di failover dell'area.

Per abilitare la registrazione sulle operazioni del piano di controllo, seguire questa procedura:

Accedere al portale di Azure e passare all'account Azure Cosmos DB.
Aprire il riquadro Impostazioni di diagnostica, specificare un Nome per i log da creare.
Selezionare ControlPlaneRequests per tipo di log e selezionare l'opzione Invia a Log Analytics.
Facoltativamente, inviare i log di diagnostica ad Archiviazione di Azure, Hub eventi di Azure, Monitoraggio di Azure o terze parti.

È anche possibile archiviare i log in un account di archiviazione o in un flusso a un hub eventi. Questo articolo illustra come inviare i log a Log Analytics e quindi eseguire query su di essi. Dopo l'abilitazione, l'applicazione dei log di diagnostica richiede alcuni minuti. Tutte le operazioni del piano di controllo eseguite dopo tale punto possono essere rilevate. Lo screenshot seguente mostra come abilitare i log del piano di controllo:

Enable control plane requests logging

Visualizzare le operazioni del piano di controllo

Dopo aver attivato la registrazione, seguire questa procedura per tenere traccia delle operazioni per un account specifico:

Accedere al portale di Azure.
Aprire la scheda Monitoraggio dal riquadro di spostamento a sinistra e quindi selezionare il riquadro Log. Apre un'interfaccia utente in cui è possibile eseguire facilmente query con tale account specifico nell'ambito. Eseguire la query seguente per visualizzare i log del piano di controllo:
```
AzureDiagnostics
| where ResourceProvider=="MICROSOFT.DOCUMENTDB" and Category=="ControlPlaneRequests"
| where TimeGenerated >= ago(1h)
```
Gli screenshot seguenti acquisisce i log quando viene modificato un livello di coerenza per un account Azure Cosmos DB. Il valore activityId_g dei risultati è diverso dall'ID attività di un'operazione:

Gli screenshot seguenti acquisiscono i log quando viene creato il keyspace o una tabella di un account Cassandra e quando viene aggiornata la velocità effettiva. I log del piano di controllo per le operazioni di creazione e aggiornamento nel database e il contenitore vengono registrati separatamente, come illustrato nello screenshot seguente:

Identificare l'identità associata a un'operazione specifica

Se si vuole eseguire ulteriormente il debug, è possibile identificare un'operazione specifica nel Log attività usando activityId_g o il timestamp dell'operazione. Il timestamp viene usato per alcuni client di Resource Manager in cui l'ID attività non viene passato in modo esplicito. Il log attività fornisce informazioni dettagliate sull'identità con cui è stata avviata l'operazione. Lo screenshot seguente mostra come usare activityId_g per trovare le operazioni associate nel log attività:

Use the activity ID and find the operations

Operazioni del piano di controllo per l'account Azure Cosmos DB

Di seguito sono riportate le operazioni del piano di controllo disponibili a livello di account. La maggior parte delle operazioni viene monitorata a livello di account. Queste operazioni sono disponibili come metriche in Monitoraggio di Azure:

Area aggiunta
Area rimossa
Account eliminato
Failover area eseguito
Account creato
Rete virtuale eliminata
Impostazioni di rete dell'account aggiornate
Impostazioni di replica dell'account aggiornate
Chiavi dell'account aggiornate
Impostazioni di backup dell'account aggiornate
Impostazioni di diagnostica dell'account aggiornate

Operazioni del piano di controllo per database o contenitori

Di seguito sono riportate le operazioni del piano di controllo disponibili a livello di database e contenitore. Queste operazioni sono disponibili come metriche in Monitoraggio di Azure:

Database SQL creato
Database SQL aggiornato
Velocità effettiva del database SQL aggiornata
Database SQL eliminato
Contenitore SQL creato
Contenitore SQL aggiornato
Velocità effettiva del contenitore SQL aggiornata
Contenitore SQL eliminato
Keyspace Cassandra creato
Keyspace Cassandra aggiornato
Velocità effettiva Keyspace Cassandra aggiornata
Keyspace Cassandra eliminato
Tabella Cassandra creata
Tabella Cassandra aggiornata
Velocità effettiva tabella Cassandra aggiornata
Tabella Cassandra eliminata
Database Gremlin creato
Database Gremlin aggiornato
Velocità effettiva database Gremlin aggiornata
Database Gremlin eliminato
Grafo Gremlin creato
Grafo Gremlin aggiornato
Velocità effettiva grafo Gremlin aggiornata
Grafo Gremlin eliminato
Database Mongo creato
Database Mongo aggiornato
Velocità effettiva database Mongo aggiornata
Database Mongo eliminato
Raccolta Mongo creata
Raccolta Mongo aggiornata
Velocità effettiva raccolta Mongo aggiornata
Raccolta Mongo eliminata
Tabella di AzureTable creata
Tabella di AzureTable aggiornata
Velocità effettiva tabella di AzureTable aggiornata
Tabella di AzureTable eliminata

Operazioni di log di diagnostica

Di seguito sono riportati i nomi delle operazioni nei log di diagnostica per operazioni diverse:

RegionAddStart, RegionAddComplete
RegionRemoveStart, RegionRemoveComplete
AccountDeleteStart, AccountDeleteComplete
RegionFailoverStart, RegionFailoverComplete
AccountCreateStart, AccountCreateComplete
AccountUpdateStart, AccountUpdateComplete
VirtualNetworkDeleteStart, VirtualNetworkDeleteComplete
DiagnosticLogUpdateStart, DiagnosticLogUpdateComplete

Per le operazioni specifiche dell'API, l'operazione viene denominata con il formato seguente:

ApiKind + ApiKindResourceType + OperationType
ApiKind + ApiKindResourceType + "Throughput" + operationType

Esempio

CassandraKeyspacesCreate
CassandraKeyspacesUpdate
CassandraKeyspacesThroughputUpdate
SqlContainersUpdate

La proprietà resourceDetails contiene l'intero corpo della risorsa come payload della richiesta e contiene tutte le proprietà richieste per l'aggiornamento

Query di log di diagnostica per le operazioni del piano di controllo

Di seguito sono riportati alcuni esempi per ottenere i log di diagnostica per le operazioni del piano di controllo:

AzureDiagnostics 
| where Category startswith "ControlPlane"
| where OperationName contains "Update"
| project httpstatusCode_s, statusCode_s, OperationName, resourceDetails_s, activityId_g

AzureDiagnostics 
| where Category =="ControlPlaneRequests"
| where TimeGenerated >= todatetime('2020-05-14T17:37:09.563Z')
| project TimeGenerated, OperationName, apiKind_s, apiKindResourceType_s, operationType_s, resourceDetails_s

AzureDiagnostics
| where Category == "ControlPlaneRequests"
| where OperationName startswith "SqlContainersUpdate"

AzureDiagnostics
| where Category == "ControlPlaneRequests"
| where OperationName startswith "SqlContainersThroughputUpdate"

Eseguire una query per ottenere il valore activityId e il chiamante che ha avviato l'operazione di eliminazione del contenitore:

(AzureDiagnostics
| where Category == "ControlPlaneRequests"
| where OperationName == "SqlContainersDelete"
| where TimeGenerated >= todatetime('9/3/2020, 5:30:29.300 PM')
| summarize by activityId_g )
| join (
AzureActivity
| parse HTTPRequest with * "clientRequestId\": \"" activityId_g "\"" * 
| summarize by Caller, HTTPRequest, activityId_g)
on activityId_g
| project Caller, activityId_g

Eseguire una query per ottenere gli aggiornamenti di indice o ttl. È quindi possibile confrontare l'output di questa query con un aggiornamento precedente per visualizzare la modifica nell'indice o ttl.

AzureDiagnostics
| where Category =="ControlPlaneRequests"
| where  OperationName == "SqlContainersUpdate"
| project resourceDetails_s

output:

{id:skewed,indexingPolicy:{automatic:true,indexingMode:consistent,includedPaths:[{path:/*,indexes:[]}],excludedPaths:[{path:/_etag/?}],compositeIndexes:[],spatialIndexes:[]},partitionKey:{paths:[/pk],kind:Hash},defaultTtl:1000000,uniqueKeyPolicy:{uniqueKeys:[]},conflictResolutionPolicy:{mode:LastWriterWins,conflictResolutionPath:/_ts,conflictResolutionProcedure:}