Condividi tramite


Diagnosticare e risolvere i problemi quando si usa .NET SDK di Azure Cosmos DB

SI APPLICA A: NoSQL

Questo articolo illustra problemi e soluzioni alternative comuni, passaggi di diagnostica e strumenti utili durante l'uso di .NET SDK con gli account Azure Cosmos DB for NoSQL. .NET SDK offre una rappresentazione logica lato client per accedere ad Azure Cosmos DB for NoSQL. Questo articolo descrive strumenti e approcci utili ad affrontare eventuali problemi.

Elenco di controllo per la risoluzione dei problemi

Considerare l'elenco di controllo seguente prima di spostare l'applicazione nell'ambiente di produzione. L'uso dell'elenco di controllo consente di prevenire diversi problemi comuni. È anche possibile diagnosticare rapidamente quando si verifica un problema:

  • Usare l'SDK più recente. Gli SDK di anteprima non devono essere usati per la produzione. In questo modo si evitano problemi noti già risolti.
  • Esaminare i suggerimenti sulle prestazioni e seguire le procedure consigliate. Ciò consentirà di evitare problemi di scalabilità, latenza e altre prestazioni.
  • Abilitare la registrazione dell'SDK per risolvere un problema. L'abilitazione della registrazione può influire sulle prestazioni, quindi è consigliabile abilitarla solo quando si riscontrano problemi. È possibile abilitare i log seguenti:
    • Registrare le metriche usando il portale di Azure. Le metriche del portale mostrano i dati di telemetria di Azure Cosmos DB, utili per determinare se il problema è correlato ad Azure Cosmos DB o se si trova sul lato client.
    • Registrare la stringa di diagnostica dalle operazioni e/o dalle eccezioni.

Diamo un'occhiata alla sezione Problemi e soluzioni alternative comuni in questo articolo.

Controllare la sezione problemi di GitHub monitorata attivamente. Verificare se è già stato pubblicato un problema simile con una soluzione alternativa. Se non è stata trovata una soluzione, segnalare un problema in GitHub. È possibile aprire un ticket di supporto per problemi urgenti.

Acquisire la diagnostica

Tutte le risposte nell'SDK, inclusa CosmosException, hanno una proprietà Diagnostics. Questa proprietà registra tutte le informazioni correlate alla singola richiesta, inclusi i tentativi effettuati o eventuali errori temporanei.

La diagnostica viene restituita come stringa. La stringa cambia con ogni versione, perché viene migliorata per la risoluzione dei problemi relativi a scenari diversi. Con ogni versione dell'SDK, la stringa include modifiche alla formattazione che causano un'interruzione. Non analizzare la stringa per evitare modifiche che causano interruzioni. L'esempio di codice seguente illustra come leggere i log di diagnostica usando .NET SDK:

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

Problemi comuni e soluzioni alternative

Suggerimenti generici

  • Seguire qualsiasi collegamento aka.ms incluso nei dettagli dell'eccezione.
  • Eseguire l'app nella stessa area di Azure dell'account Azure Cosmos DB, quando possibile.
  • È possibile che si verifichino problemi di connettività/disponibilità a causa della mancanza di risorse nel computer client. È consigliabile monitorare l'utilizzo della CPU nei nodi che eseguono il client Azure Cosmos DB e dimensionare le prestazioni se sono in esecuzione con un carico elevato.

Controllare le metriche del portale

Controllare le metriche del portale per determinare se si tratta di un problema sul lato client o se si è verificato un problema con il servizio. Ad esempio, se le metriche contengono una frequenza elevata di richieste a velocità limitata (codice di stato HTTP 429), significa che la richiesta viene limitata. Controllare la sezione Frequenza richieste troppo grande.

Riprovare a progettare

Vedere la guida per la progettazione di applicazioni resilienti con Azure Cosmos DB SDK per indicazioni su come progettare applicazioni resilienti e conoscere la semantica di retry dell'SDK.

SNAT

Se l'app viene distribuita in macchine virtuali di Azure senza un indirizzo IP pubblico, per impostazione predefinita le porte SNAT di Azure stabiliscono le connessioni a qualsiasi endpoint all'esterno della macchina virtuale. Il numero di connessioni consentite dalla macchina virtuale all'endpoint di Azure Cosmos DB è limitato dalla configurazione SNAT di Azure. Questa situazione può causare la limitazione della connessione, la chiusura della connessione o i timeout della richiesta indicati in precedenza.

Le porte SNAT di Azure vengono usate solo quando la macchina virtuale ha un indirizzo IP privato e si connette a un indirizzo IP pubblico. Esistono due soluzioni alternative per evitare la limitazione SNAT di Azure (purché si stia già usando una singola istanza client nell'intera applicazione):

  • Aggiungere l'endpoint del servizio Azure Cosmos DB alla subnet della rete virtuale di macchine virtuali di Azure. Per altre informazioni, vedere Endpoint servizio di rete virtuale di Azure.

    Quando l'endpoint del servizio è abilitato, le richieste non vengono più inviate da un indirizzo IP pubblico ad Azure Cosmos DB. Vengono invece inviate le identità di rete virtuale e subnet. Questa modifica può comportare blocchi del firewall se sono consentiti solo indirizzi IP pubblici. Se si usa un firewall, quando si abilita l'endpoint del servizio, aggiungere una subnet al firewall tramite ACL di rete virtuale.

  • Assegnare un indirizzo IP pubblico alla macchina virtuale di Azure.

Latenza di rete elevata

Per informazioni dettagliate sulla risoluzione dei problemi di latenza, vedere la guida alla risoluzione dei problemi di latenza.

Errori di autenticazione proxy

Se vengono visualizzati errori HTTP 407:

Response status code does not indicate success: ProxyAuthenticationRequired (407);

Questo errore non viene generato dall'SDK e non proviene dal servizio Azure Cosmos DB. Si tratta di un errore correlato alla configurazione della rete. È probabile che nella configurazione di rete manchi l'autenticazione proxy necessaria. Se non si prevede di usare un proxy, contattare il team responsabile della rete. Se si usa un proxy, assicurarsi di impostare la configurazione WebProxy corretta in CosmosClientOptions.WebProxy durante la creazione dell'istanza del client.

Problemi di query comuni

Le metriche di query consentono di determinare dove la query sta spendendo la maggior parte del tempo. Dalle metriche di query è possibile visualizzare la quantità di spesa per il back-end rispetto al client. Per altre informazioni, vedere la guida alle prestazioni delle query.

Se si verifica l'errore seguente: Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies: e si usa Windows, è consigliabile eseguire l'aggiornamento alla versione più recente di Windows.

Passaggi successivi

  • Informazioni sulle linee guida sulle prestazioni per .NET SDK
  • Informazioni sulle procedure consigliate per .NET SDK