Suggerimenti sulle prestazioni per Azure Cosmos DB e .NET SDK v2

  • Articolo

SI APPLICA A: NoSQL

Azure Cosmos DB è un database distribuito veloce e flessibile, facilmente scalabile e con latenza e velocità effettiva garantite. Non è necessario apportare modifiche significative all'architettura o scrivere codice complesso per dimensionare il database con Azure Cosmos DB. Aumentare o ridurre le prestazioni è semplice come eseguire una singola chiamata API. Per altre informazioni, vedere Effettuare il provisioning della velocità effettiva per un contenitore oppure Effettuare il provisioning della velocità effettiva per un database. Dato che si accede ad Azure Cosmos DB tramite chiamate di rete, è tuttavia possibile apportare ottimizzazioni lato client per ottenere prestazioni ottimali se si usa l'SQL .NET SDK.

Pertanto, se si sta tentando di migliorare le prestazioni del database, prendere in considerazione queste opzioni:

Eseguire l'aggiornamento all'SDK .NET V3

Viene rilasciato l'SDK .NET v3. Se si usa .NET v3 SDK, vedere la Guida alle prestazioni .NET v3 per le informazioni seguenti:

  • Per impostazione predefinita, la modalità è TCP diretta
  • Supporto dell'API di flusso
  • Supporto del serializzatore personalizzato per consentire l'utilizzo di System.Text.JSON
  • Supporto batch e bulk integrato

Raccomandazioni relative all'hosting

Attivare Garbage Collection (GC) lato server

In alcuni casi, può essere utile ridurre la frequenza di Garbage Collection. In .NET impostare gcServer su true.

Aumentare il carico di lavoro client

Se si sta eseguendo il test a livelli di velocità effettiva elevati (più di 50.000 UR/sec), l'applicazione client potrebbe diventare un collo di bottiglia a causa della limitazione di uso della CPU o della rete. In questo caso, è possibile continuare a effettuare il push dell'account Azure Cosmos DB aumentando il numero di istanze delle applicazioni client in più server.

Nota

Un uso elevato della CPU può causare un aumento della latenza e le eccezioni di timeout delle richieste.

Operazioni sui metadati

Non verificare l'esistenza di un database e/o di una raccolta chiamando Create...IfNotExistsAsync e/o Read...Async nel percorso critico e/o prima di eseguire un'operazione sull'elemento. La convalida deve essere eseguita solo all'avvio dell'applicazione quando è necessario, se si prevede che verrà eliminata (in caso contrario non è necessario). Queste operazioni sui metadati genereranno una latenza end-to-end aggiuntiva, non hanno contratto di servizio e generano le proprie limitazioni separate che non si ridimensionano come le operazioni sui dati.

Registrazione e traccia

Per alcuni ambienti è abilitato .NET DefaultTraceListener. DefaultTraceListener pone problemi di prestazioni negli ambienti di produzione causando colli di bottiglia elevati di CPU e I/O. Controllare e assicurarsi che DefaultTraceListener sia disabilitato per l'applicazione rimuovendolo da TraceListeners negli ambienti di produzione.

Le versioni più recenti dell'SDK (successive alla 2.16.2) lo rimuovono automaticamente quando lo rilevano, con le versioni precedenti, è possibile rimuoverlo tramite:

if (!Debugger.IsAttached)
{
    Type defaultTrace = Type.GetType("Microsoft.Azure.Documents.DefaultTrace,Microsoft.Azure.DocumentDB.Core");
    TraceSource traceSource = (TraceSource)defaultTrace.GetProperty("TraceSource").GetValue(null);
    traceSource.Listeners.Remove("Default");
    // Add your own trace listeners
}

Rete

Criteri di connessione: usare la modalità di connessione diretta

La modalità di connessione predefinita di .NET V2 SDK è il gateway. La modalità di connessione viene configurata durante la costruzione dell'istanza di DocumentClient usando il parametro ConnectionPolicy. Se si usa la modalità diretta, è necessario impostare anche Protocol usando il parametro ConnectionPolicy. Per altre informazioni sulle diverse opzioni di connettività, consultare l'articolo modalità di connettività.

Uri serviceEndpoint = new Uri("https://contoso.documents.net");
string authKey = "your authKey from the Azure portal";
DocumentClient client = new DocumentClient(serviceEndpoint, authKey,
new ConnectionPolicy
{
   ConnectionMode = ConnectionMode.Direct, // ConnectionMode.Gateway is the default
   ConnectionProtocol = Protocol.Tcp
});

Esaurimento della porta temporanea

Se si rileva un volume di connessione elevato o un uso elevato delle porte nelle istanze, verificare prima di tutto che le istanze client siano singleton. In altre parole, le istanze client devono essere univoche per la durata dell'applicazione.

Quando è in esecuzione sul protocollo TCP, il client ottimizza la latenza usando connessioni di lunga durata anziché il protocollo HTTPS, che termina le connessioni dopo due minuti di inattività.

Negli scenari con accesso sporadico, se si nota un numero di connessioni superiore rispetto alla modalità di accesso Gateway, è possibile:

  • Configurare la proprietà ConnectionPolicy.PortReuseMode per PrivatePortPool (efficace con la versione del framework>= 4.6.1 e la versione di .NET Core >= 2.0): questa proprietà consente all'SDK di usare un piccolo pool di porte temporanee per diversi endpoint di destinazione di Azure Cosmos DB.
  • Configurare la proprietà ConnectionPolicy.IdleConnectionTimeout perché sia maggiore o uguale a 10 minuti. I valori consigliati sono compresi tra 20 minuti e 24 ore.

Chiamare OpenAsync per evitare la latenza di avvio alla prima richiesta

Per impostazione predefinita, la prima richiesta ha una latenza più elevata perché deve recuperare la tabella di routing degli indirizzi. Quando si usa SDK V2, chiamare OpenAsync() una volta durante l'inizializzazione per evitare questa latenza di avvio nella prima richiesta. La chiamata è simile alla seguente: await client.OpenAsync();

Nota

OpenAsync genererà richieste per ottenere la tabella di routing degli indirizzi per tutti i contenitori nell'account. Per gli account con molti contenitori, ma la cui applicazione accede a un sottoinsieme di tali contenitori, OpenAsync genererebbe una quantità di traffico non necessaria, rallentando l'inizializzazione. Pertanto, l'uso di OpenAsync potrebbe non essere utile in questo scenario perché rallenta l'avvio dell'applicazione.

Collocare i client nella stessa area di Azure per ottenere migliori prestazioni

Quando possibile, posizionare eventuali applicazioni che chiamano Azure Cosmos DB nella stessa area del database Azure Cosmos DB. Ecco un confronto approssimativo: le chiamate ad Azure Cosmos DB all'interno della stessa area vengono completate entro 1 ms a 2 ms, ma la latenza tra la costa occidentale e orientale degli Stati Uniti è superiore a 50 ms. Questa latenza può variare da richiesta a richiesta, in base alla route seguita dalla richiesta durante il passaggio dal client al limite del data center di Azure. È possibile ottenere la latenza più bassa possibile assicurandosi che l'applicazione chiamante si trovi nella stessa area di Azure in cui si trova l'endpoint di Azure Cosmos DB con provisioning. Per un elenco delle aree disponibili, vedere Aree di Azure.

Criteri di connessione di Azure Cosmos DB

Aumentare il numero di thread/attività

Poiché le chiamate ad Azure Cosmos DB vengono eseguite sulla rete, può essere necessario modificare il grado di parallelismo delle richieste in modo che i tempi di attesa dell'applicazione client tra le richieste siano minimi. Se si usa Task Parallel Library di .NET, ad esempio, creare centinaia di attività di lettura o scrittura in Azure Cosmos DB.

Abilitare la rete accelerata

Per ridurre la latenza e l'instabilità della CPU, si consiglia di abilitare la rete accelerata nelle macchine virtuali client. Vedere l'articolo Creare una macchina virtuale Windows con rete accelerata oppure l'articolo Creare una macchina virtuale Linux con rete accelerata.

Uso dell'SDK

Installare l'SDK più recente

Agli SDK di Azure Cosmos DB vengono apportati continui miglioramenti per offrire prestazioni ottimali. Per determinare la versione di SDK più recente e verificare i miglioramenti, vedere le pagine relative agli SDK di Azure Cosmos DB.

Usare un client Azure Cosmos DB singleton per la durata dell'applicazione

Ogni istanza di DocumentClient è thread-safe ed esegue la gestione efficiente delle connessioni e la memorizzazione nella cache degli indirizzi quando funziona in modalità diretta. Per consentire una gestione efficiente delle connessioni e prestazioni migliori del client SDK, è consigliabile usare una singola istanza per ogni AppDomain per la durata dell'applicazione.

Evitare le chiamate di blocco

L'SDK di Azure Cosmos DB deve essere progettato per elaborare più richieste contemporaneamente. Le API asincrone consentono a un piccolo pool di thread di gestire migliaia di richieste simultanee senza attendere chiamate di blocco. Anziché attendere il completamento di un'attività sincrona a esecuzione prolungata, il thread può lavorare su un'altra richiesta.

Un problema di prestazioni comune nelle app che usano l'SDK di Azure Cosmos DB sono le chiamate di blocco che potrebbero essere asincrone. Molte chiamate di blocco sincrone causano la scadenza del pool di thread e tempi di risposta degradati.

Non:

  • Bloccare l'esecuzione asincrona chiamando Task.Wait o Task.Result.
  • Usare Task.Run per rendere asincrona un'API sincrona.
  • Acquisire blocchi in percorsi di codice comuni. .NET SDK di Azure Cosmos DB è più efficiente quando progettato per eseguire codici in parallelo.
  • Chiamare Task.Run e attendere immediatamente. ASP.NET Core esegue già il codice dell'app nei normali thread del pool, quindi la chiamata a Task.Run comporta solo una pianificazione aggiuntiva del pool di thread non necessaria. Anche se il codice pianificato blocca un thread, Task.Run non lo impedisce.
  • Usare ToList() su DocumentClient.CreateDocumentQuery(...) che usa chiamate di blocco per svuotare in modo sincrono la query. Usare AsDocumentQuery() per svuotare la query in modo asincrono.

Fare:

  • Chiamare le API .NET di Azure Cosmos DB in modo asincrono.
  • L'intero stack di chiamate è asincrono per trarre vantaggio dai criteri async/await.

Un profiler, ad esempio PerfView, può essere usato per trovare i thread aggiunti di frequente al pool di thread. L'evento Microsoft-Windows-DotNETRuntime/ThreadPoolWorkerThread/Start indica un thread aggiunto al pool di thread.

Aumentare il valore di System.Net MaxConnections per host se si usa la modalità Gateway

Le richieste di Azure Cosmos DB vengono effettuate tramite HTTPS/REST quando si usa la modalità gateway. Sono soggette al limite di connessione predefinito per nome host o indirizzo IP. Potrebbe essere necessario impostare MaxConnections su un valore più alto (da 100 a 1.000) per consentire alla libreria client di usare più connessioni simultanee ad Azure Cosmos DB. In .NET SDK 1.8.0 e versioni successive il valore predefinito per ServicePointManager.DefaultConnectionLimit è 50. Per modificare il valore, è possibile impostare Documents.Client.ConnectionPolicy.MaxConnectionLimit su un valore superiore.

Implementare il backoff in corrispondenza di intervalli RetryAfter

Durante il test delle prestazioni, è necessario aumentare il carico fino a limitare un numero ridotto di richieste. Se le richieste sono limitate, l'applicazione client deve eseguire il backoff sulla limitazione per l'intervallo tra tentativi specificato dal server. Rispettando il backoff si garantiscono tempi di attesa minimi tra i tentativi.

Il supporto dei criteri di ripetizione dei tentativi è incluso in questi SDK:

Per altre informazioni, vedere RetryAfter.

Nella versione 1.19 e successive di .NET SDK c'è un meccanismo per registrare le informazioni di diagnostica aggiuntive e risolvere i problemi di latenza come mostrato nell'esempio seguente. È possibile registrare la stringa di diagnostica per le richieste che hanno una latenza di lettura più elevata. La stringa di diagnostica acquisita consente di comprendere quante volte sono stati ricevuti errori 429 per una determinata richiesta.

ResourceResponse<Document> readDocument = await this.readClient.ReadDocumentAsync(oldDocuments[i].SelfLink);
readDocument.RequestDiagnosticsString

Memorizzare nella cache gli URI dei documenti per una minore latenza di lettura

Memorizzare nella cache gli URI dei documenti quando possibile per ottenere prestazioni di lettura ottimali. È necessario definire la logica per memorizzare nella cache l'ID risorsa quando si crea una risorsa. Le ricerche basate sugli ID risorsa sono più veloci rispetto alle ricerche basate sul nome, quindi la memorizzazione nella cache di questi valori migliora le prestazioni.

Aumentare il numero di thread/attività

Vedere Aumentare il numero di thread/attività nella sezione Rete di questo articolo.

Operazioni di query

Per le operazioni di query, vedere i suggerimenti sulle prestazioni per le query.

Criterio di indicizzazione

Escludere i percorsi non usati dall'indicizzazione per scritture più veloci

I criteri di indicizzazione di Azure Cosmos DB consentono anche di specificare i percorsi dei documenti da includere o escludere dall'indicizzazione usando i percorsi di indicizzazione (IndexingPolicy.IncludedPaths e IndexingPolicy.ExcludedPaths). I percorsi di indicizzazione possono migliorare le prestazioni di scrittura e ridurre l'archiviazione degli indici per gli scenari in cui i modelli di query sono noti in precedenza. Ciò è dovuto al fatto che i costi di indicizzazione sono correlati direttamente al numero di percorsi univoci indicizzati. Questo codice, ad esempio, mostra come escludere dall'indicizzazione un'intera sezione dei documenti (sottoalbero) usando il carattere jolly "*":

var collection = new DocumentCollection { Id = "excludedPathCollection" };
collection.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
collection.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/nonIndexedContent/*");
collection = await client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("db"), collection);

Per altre informazioni, vedere l'articolo relativo ai criteri di indicizzazione di Azure Cosmos DB.

Velocità effettiva

Misurare e ottimizzare per ottenere un uso minore di unità richiesta al secondo

Azure Cosmos DB offre un set completo di operazioni di database. Queste operazioni includono query relazionali e gerarchiche con file UDF, stored procedure e trigger, operative nei documenti in una raccolta di database. Il costo associato a ognuna di queste operazioni dipende da CPU, I/O e memoria necessari per il completamento dell'operazione. Invece di preoccuparsi delle risorse hardware e della relativa gestione, è possibile considerare un'unità di richiesta come singola misura per le risorse necessarie per eseguire diverse operazioni di database e soddisfare una richiesta di applicazione.

Viene eseguito il provisioning della velocità effettiva in base al numero di unità richiesta impostato per ogni contenitore. Il consumo delle unità di richiesta è valutato in base alla frequenza al secondo. Le applicazioni che superano la frequenza di unità richiesta con provisioning previsto per il contenitore sono limitate fino al ritorno della frequenza sotto il valore riservato per il contenitore. Se l'applicazione necessita di un livello superiore di velocità effettiva, sarà possibile aumentare la velocità effettiva eseguendo il provisioning di unità richiesta aggiuntive.

La complessità di una query influisce sul numero di unità richiesta usate per un'operazione. Il numero di predicati, la natura dei predicati, il numero di UDF e le dimensioni del set di dati di origine sono tutti fattori che incidono sul costo delle operazioni di query.

Per misurare l'overhead di qualunque operazione (create, update o delete), esaminare l'intestazione x-ms-request-charge (o la proprietà RequestCharge equivalente in ResourceResponse\<T> oppure FeedResponse\<T> in .NET SDK) per determinare il numero di unità richiesta usate da queste operazioni:

// Measure the performance (Request Units) of writes
ResourceResponse<Document> response = await client.CreateDocumentAsync(collectionSelfLink, myDocument);
Console.WriteLine("Insert of document consumed {0} request units", response.RequestCharge);
// Measure the performance (Request Units) of queries
IDocumentQuery<dynamic> queryable = client.CreateDocumentQuery(collectionSelfLink, queryString).AsDocumentQuery();
while (queryable.HasMoreResults)
    {
        FeedResponse<dynamic> queryResponse = await queryable.ExecuteNextAsync<dynamic>();
        Console.WriteLine("Query batch consumed {0} request units", queryResponse.RequestCharge);
    }

L'addebito richiesta restituito in questa intestazione è una frazione della velocità effettiva con provisioning, ossia 2.000 UR/secondo. Se, ad esempio, la query precedente restituisce 1.000 documenti da 1 KB, il costo dell'operazione è 1.000. Entro un secondo, il server rispetterà quindi solo due richieste di questo tipo prima di limitare la velocità delle richieste successive. Per altre informazioni, vedere Unità richiesta e il calcolatore di unità richiesta.

Gestire la limitazione della frequenza o una frequenza di richieste troppo elevata

Quando un client prova a superare la velocità effettiva riservata per un account, non si verifica alcun calo delle prestazioni del server e l'uso della capacità della velocità effettiva non supera il livello riservato. Il server terminerà preventivamente la richiesta con RequestRateTooLarge (codice di stato HTTP 429). Restituirà un'intestazione x-ms-retry-after-ms che indica la quantità di tempo, espressa in millisecondi, che l'utente deve attendere prima di ripetere la richiesta.

HTTP Status 429,
Status Line: RequestRateTooLarge
x-ms-retry-after-ms :100

Tutti gli SDK intercettano implicitamente questa risposta, rispettano l'intestazione retry-after specificata dal server e ripetono la richiesta. A meno che all'account non accedano contemporaneamente più client, il tentativo successivo riuscirà.

Se si dispone di più client che operano complessivamente a una velocità costantemente superiore a quella della richiesta, il numero di tentativi predefinito attualmente impostato internamente dal client su 9 potrebbe non essere sufficiente. In tal caso, il client genera un'eccezione DocumentClientException con codice di stato 429 per l'applicazione.

È possibile modificare il numero di tentativi predefinito impostando RetryOptions nell'istanza ConnectionPolicy. Per impostazione predefinita, l'eccezione DocumentClientException con codice di stato 429 viene restituita dopo un tempo di attesa cumulativo di 30 secondi, se la richiesta continua a funzionare al di sopra della frequenza delle richieste. Questo errore si verifica anche quando il numero di ripetizioni dei tentativi corrente è inferiore al numero massimo di tentativi, indipendentemente dal fatto che si tratti del valore predefinito 9 o di un valore definito dall'utente.

Il comportamento automatizzato per la ripetizione dei tentativi consente di migliorare la resilienza e l'usabilità per la maggior parte delle applicazioni. Ma potrebbe non essere il comportamento migliore quando si eseguono benchmark delle prestazioni, soprattutto quando si misura la latenza. La latenza osservata dal client presenterà dei picchi se l'esperimento raggiunge il limite del server e fa in modo che l'SDK client ripeta automaticamente i tentativi. Per evitare i picchi di latenza durante gli esperimenti relativi alle prestazioni, misurare l'addebito restituito da ogni operazione e assicurarsi che le richieste operino al di sotto della frequenza delle richieste riservata. Per altre informazioni, vedere Unità richiesta.

Per ottenere una velocità effettiva maggiore, progettare documenti di dimensioni minori

L'addebito per le richieste (ovvero il costo di elaborazione delle richieste) per una data operazione è correlato direttamente alle dimensioni del documento. Le operazioni sui documenti di grandi dimensioni sono più costose rispetto alle operazioni sui documenti di piccole dimensioni.

Passaggi successivi

Per un'applicazione di esempio che viene usata per valutare Azure Cosmos DB per scenari a prestazioni elevate su un numero ridotto di computer client, vedere Test delle prestazioni e della scalabilità con Azure Cosmos DB.

Per altre informazioni sulla progettazione dell'applicazione per scalabilità e prestazioni elevate, vedere l'articolo relativo a partizionamento e ridimensionamento in Azure Cosmos DB.