Procedure consigliate per Azure Cosmos DB Java SDK

  • Articolo

SI APPLICA A: NoSQL

Questo articolo illustra le procedure consigliate per l'uso di Azure Cosmos DB Java SDK. Seguendo queste procedure, sarà possibile aumentare la latenza e la disponibilità e migliorare le prestazioni complessive.

Elenco di controllo

Selezionato Argomento Dettagli/Collegamenti
Versione dell'SDK Usare sempre la versione più recente di Azure Cosmos DB SDK disponibile per ottenere prestazioni ottimali.
Client singleton Per prestazioni migliori, usare un'istanza singola di CosmosClient per tutta la durata dell'applicazione.
Aree Per ridurre la latenza, assicurarsi di eseguire l'applicazione nella stessa area di Azure dell'account Azure Cosmos DB, laddove possibile. Abilitare da due a quattro aree e replicare gli account in più aree per ottenere la migliore disponibilità. Per i carichi di lavoro di produzione, abilitare il failover gestito dal servizio. In assenza di questa configurazione, l'account riscontrerà perdite di disponibilità di scrittura per tutta la durata dell'interruzione dell'area di scrittura, perché il failover manuale avrà esito negativo a causa della mancanza di connettività dell'area. Per informazioni su come aggiungere più aree usando Java SDK, vedere qui
Disponibilità e failover Impostare preferredRegions nell'SDK V4. Durante i failover, le operazioni di scrittura vengono inviate all'area di scrittura corrente e tutte le letture vengono inviate alla prima area all'interno dell'elenco delle aree preferite. Per altre informazioni sui meccanismi di failover a livello di area, vedere la Guida alla risoluzione dei problemi di disponibilità.
CPU È possibile che si verifichino problemi di connettività/disponibilità a causa della mancanza di risorse nel computer client. Monitorare l'utilizzo della CPU nei nodi che eseguono il client Azure Cosmos DB e aumentare le prestazioni o il numero di istanze se l'utilizzo è molto elevato.
Hosting Per la maggior parte dei casi comuni dei carichi di lavoro di produzione, è consigliabile usare almeno macchine virtuali con 4 core e 8 GB di memoria quando possibile.
Modalità di connettività Usare la modalità diretta per ottenere prestazioni ottimali. Per istruzioni dettagliate su come eseguire questa operazione, vedere la documentazione dell'SDK V4.
Rete Se si usa una macchina virtuale per eseguire l'applicazione, abilitare Rete accelerata nella macchina virtuale per evitare i colli di bottiglia dovuti a traffico elevato e ridurre la latenza o l'instabilità della CPU. È anche possibile valutare l'uso di una macchina virtuale di livello superiore in cui l'utilizzo massimo della CPU è inferiore al 70%.
Esaurimento delle porte temporanee Per le connessioni occasionali o sporadiche, è consigliabile impostare idleEndpointTimeout su un valore superiore. La proprietà idleEndpointTimeout in DirectConnectionConfig consente di controllare il tempo trascorso il quale le connessioni inutilizzate vengono chiuse. In questo modo si riduce il numero di connessioni inutilizzate. Per impostazione predefinita, le connessioni inattive a un endpoint vengono mantenute aperte per 1 ora. Se non sono presenti richieste a un endpoint specifico per la durata del timeout di inattività dell'endpoint, il client diretto chiude tutte le connessioni a tale endpoint per risparmiare risorse e costi di I/O.
Usare l'utilità di pianificazione appropriata (evitare l'acquisizione di thread Netty di I/O EventLoop) Evitare le chiamate di blocco: .block(). L'intero stack di chiamate è asincrono al fine di sfruttare modelli di API asincroni e l'utilizzo di thread e utilità di pianificazione appropriati
Timeout end-to-end Per ottenere timeout end-to-end, implementare criteri di timeout end-to-end in Java SDK. Per informazioni dettagliate sui timeout con Azure Cosmos DB vedere qui
Logica di ripetizione dei tentativi Un errore temporaneo è un errore che ha una causa sottostante che si risolve presto da sola. Le applicazioni che si connettono al database devono essere sviluppate in modo da prevedere tali errori temporanei. Per gestirli, implementare la logica di ripetizione dei tentativi nel codice invece di mostrarli agli utenti come errori dell'applicazione. L'SDK ha una logica predefinita per gestire questi errori temporanei nelle richieste ripetibili, come le operazioni di lettura o query. L'SDK non ritenterà le scritture per gli errori temporanei perché le scritture non sono idempotenti. L'SDK consente agli utenti di configurare la logica di ripetizione dei tentativi per le limitazioni. Per informazioni dettagliate sugli errori per cui effettuare il retry, vedere qui
Memorizzazione nella cache dei nomi di database/raccolta Recuperare i nomi dei database e dei contenitori dalla configurazione oppure memorizzarli nella cache all'avvio. Le chiamate come CosmosAsyncDatabase#read() o CosmosAsyncContainer#read() genereranno chiamate di metadati al servizio, il cui utilizzo viene conteggiato ai fini del limite di UR riservate dal sistema. Inoltre, l'operazione createDatabaseIfNotExists() deve essere usata una sola volta per configurare il database. Nel complesso, queste operazioni devono essere eseguite raramente.
Query parallele Azure Cosmos DB SDK supporta l'esecuzione di query in parallelo per migliorare la latenza e la velocità effettiva nelle query. È consigliabile impostare la proprietà maxDegreeOfParallelism in CosmosQueryRequestsOptions sul numero di partizioni disponibili. Se non si è a conoscenza del numero di partizioni, impostare il valore su -1, che offre la latenza migliore. Impostare inoltre maxBufferedItemCount sul numero previsto di risultati restituiti per limitare il numero di risultati di prelettura.
Backoff dei test delle prestazioni Quando si eseguono test sull'applicazione, è necessario implementare i backoff a intervalli RetryAfter. Rispettando il backoff si garantiscono tempi di attesa minimi tra i tentativi.
Indicizzazione 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#getIncludedPaths() e IndexingPolicy#getExcludedPaths(). Assicurarsi di escludere i percorsi inutilizzati dall'indicizzazione per scritture più veloci. Per un esempio su come creare indici usando l'SDK, vedere qui
Dimensioni del documento L'addebito per le richieste per un'operazione specifica è correlato direttamente alle dimensioni del documento. È consigliabile ridurre le dimensioni dei documenti, in quanto le operazioni su documenti di grandi dimensioni costano più delle operazioni su documenti più piccoli.
Dimensioni pagina Per impostazione predefinita, i risultati delle query vengono restituiti in blocchi di 100 elementi o 4 MB, a seconda del limite che viene raggiunto prima. Se una query restituirà più di 100 elementi, aumentare le dimensioni della pagina per ridurre il numero di round trip necessari. L'utilizzo della memoria aumenterà man mano che le dimensioni della pagina aumentano.
Abilitazione delle metriche delle query Per altre registrazioni delle esecuzioni di query back-end, seguire le istruzioni su come acquisire le metriche delle query SQL usando Java SDK
Registrazione SDK Usare la registrazione SDK per acquisire informazioni di diagnostica aggiuntive e risolvere i problemi di latenza. Registrare CosmosDiagnostics in Java SDK per informazioni di diagnostica più dettagliate su Azure Cosmos DB per la richiesta corrente al servizio. Come caso d'uso di esempio, acquisire la diagnostica per qualsiasi eccezione e per le operazioni completate se CosmosDiagnostics#getDuration() è maggiore di un valore soglia designato (ad esempio, se si dispone di un contratto di servizio di 10 secondi, acquisire la diagnostica quando getDuration()> 10 secondi). È consigliabile usare questi dati di diagnostica solo durante i test delle prestazioni. Per altre informazioni, seguire Acquisire la diagnostica in Java SDK
Evitare l'uso di caratteri speciali negli identificatori L'uso dei caratteri seguenti è limitato e non è consentito in alcuni identificatori: '/', '\', '?', '#'. È consigliabile non usare caratteri speciali negli identificatori come nome del database, nome della raccolta, ID elemento o chiave di partizione per evitare comportamenti imprevisti.

Procedure consigliate per l'uso della 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 maxConnectionPoolSize su un valore diverso (da 100 a 1.000) per consentire alla libreria client di usare più connessioni simultanee ad Azure Cosmos DB. In Java SDK v4 il valore predefinito per GatewayConnectionConfig#maxConnectionPoolSize è 1.000. Per modificare il valore, è possibile impostare GatewayConnectionConfig#maxConnectionPoolSize su un valore diverso.

Procedure consigliate per carichi di lavoro con un numero elevato di scritture

Per i carichi di lavoro con un numero elevato di payload di creazione, impostare l'opzione della richiesta CosmosClientBuilder#contentResponseOnWriteEnabled() su false. Il servizio non restituirà più la risorsa creata o aggiornata all'SDK. In genere, poiché l'applicazione ha l'oggetto che viene creato, non è necessario che il servizio lo restituisca. I valori dell'intestazione sono ancora accessibili, ad esempio un addebito della richiesta. La disabilitazione della risposta al contenuto può contribuire a migliorare le prestazioni, perché l'SDK non deve più allocare memoria o serializzare il corpo della risposta. Riduce inoltre l'uso della larghezza di banda di rete per migliorare ulteriormente le prestazioni.

Passaggi successivi

Per altre informazioni relative ai suggerimenti sulle prestazioni per Java SDK, vedere Suggerimenti per le prestazioni di Java SDK v4 per 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.

Si sta tentando di pianificare la capacità per una migrazione ad Azure Cosmos DB? È possibile usare le informazioni del cluster di database esistente per la pianificazione della capacità.