Condividi tramite

Suggerimenti sulle prestazioni per Azure Cosmos DB Python SDK

SI APPLICA A: NoSQL

Importante

I suggerimenti sulle prestazioni riportati in questo articolo riguardano esclusivamente Azure Cosmos DB Python SDK. Per altre informazioni, vedere il file READMEnote sulla versione di Python SDK di Azure Cosmos DB, il pacchetto (PyPI),il pacchetto (Conda) e la guida alla risoluzione dei problemi.

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 ridimensionare il database con Azure Cosmos DB. Aumentare o ridurre le prestazioni è semplice come eseguire una singola chiamata API o una chiamata al metodo SDK. Tuttavia, dato che si accede ad Azure Cosmos DB tramite chiamate di rete, è possibile introdurre ottimizzazioni sul lato client per ottenere massime prestazioni durante l'uso di Azure Cosmos DB Python SDK.

Se si vogliono migliorare le prestazioni del database, valutare le opzioni seguenti:

Rete

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

Quando possibile, posizionare eventuali applicazioni che chiamano Azure Cosmos DB nella stessa area del database Azure Cosmos DB. Per un confronto approssimativo, le chiamate ad Azure Cosmos DB eseguite nella stessa area vengono completate entro 1-2 millisecondi, mentre la latenza tra la costa occidentale e quella orientale degli Stati Uniti è >50 millisecondi. 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.

Illustrazione dei criteri di connessione di Azure Cosmos DB.

Un'app che interagisce con un account Azure Cosmos DB per più aree deve configurare località preferite per garantire che le richieste vengano inviate a un'area collocata.

Abilitare la rete accelerata per ridurre la latenza e l'instabilità della CPU

Per ottimizzare le prestazioni (ridurre la latenza e instabilità della CPU), è consigliabile seguire le istruzioni per abilitare la rete accelerata nella macchina virtuale di Azure con Windows (selezionare per istruzioni) o Linux (selezionare per istruzioni).

Senza rete accelerata, le operazioni di IO che transitano tra la macchina virtuale di Azure e le altre risorse di Azure potrebbero essere instradate inutilmente attraverso un host e un commutatore virtuale posizionato tra la macchina virtuale e la relativa scheda di rete. La presenza dell'host e del commutatore virtuale inline nel percorso dei dati non solo aumenta la latenza e l'instabilità nel canale di comunicazione, ma sottrae anche cicli della CPU alla macchina virtuale. Grazie alla rete accelerata, la macchina virtuale si interfaccia direttamente con la scheda di interfaccia di rete senza intermediari. Tutti i dettagli dei criteri di rete gestiti dall'host e dal commutatore virtuale vengono ora gestiti nell'hardware della scheda di interfaccia di rete. L'host e il commutatore virtuale vengono ignorati. Quando si abilita la rete accelerata, è in genere possibile prevedere una latenza più bassa e una velocità effettiva più elevata, oltre a una maggiore latenza coerente e a un minore utilizzo della CPU.

Limitazioni: la rete accelerata deve essere supportata nel sistema operativo della macchina virtuale e può essere abilitata solo quando la macchina virtuale viene arrestata e deallocata. La macchina virtuale non può essere distribuita con Azure Resource Manager. Servizio app non ha alcuna rete accelerata abilitata.

Per altri dettagli, vedere le istruzioni per Windows e Linux.

Disponibilità elevata

Per indicazioni generali sulla configurazione della disponibilità elevata in Azure Cosmos DB, vedere Disponibilità elevata in Azure Cosmos DB.

Oltre a una configurazione di base valida nella piattaforma di database, è possibile implementare un interruttore a livello di partizione in Python SDK, che può essere utile in scenari di interruzione del servizio. Questa funzionalità offre problemi avanzati di disponibilità dei meccanismi, che vanno oltre le funzionalità di ripetizione tra aree integrate nell'SDK per impostazione predefinita. Ciò può migliorare significativamente la resilienza e le prestazioni dell'applicazione, in particolare in condizioni di carico elevato o danneggiato.

Interruttore a livello di partizione

L'interruttore a livello di partizione (PPCB) in Python SDK migliora la disponibilità e la resilienza monitorando l'integrità delle singole partizioni fisiche e indirizzando le richieste da quelle problematiche. Questa funzionalità è particolarmente utile per la gestione di problemi temporanei e terminal, ad esempio problemi di rete, aggiornamenti delle partizioni o migrazioni.

PPCB è applicabile negli scenari seguenti:

  • Qualsiasi livello di coerenza
  • Operazioni con chiave di partizione (letture/scritture puntuali)
  • Account di area di scrittura singola con più aree di lettura
  • Più account con regioni di scrittura

Come funziona

Le partizioni passano attraverso quattro stati - Tentativo integro, Non integro, Non integro e Tentativo integro - in base all'esito positivo o negativo delle richieste:

  1. Rilevamento errori: L'SDK monitora le percentuali di errore (ad esempio, 5xx, 408) per partizione in una finestra di un minuto. Gli errori consecutivi per partizione vengono rilevati in modo illimitato dall'SDK.
  2. Contrassegno come non disponibile: Se una partizione supera le soglie configurate, viene contrassegnata come Tentativo non integro ed esclusa dal routing per 1 minuto.
  3. Transizione allo stato non sano o ripristino: Se i tentativi di ripristino hanno esito negativo, la partizione passa a Non sano. Dopo un intervallo di attesa, viene eseguito un probe Tentativo integro con una richiesta a tempo limitato per determinare il recupero.
  4. Reintegrazione: se il probe provvisorio ha esito positivo, la partizione torna a Integro. In caso contrario, rimane non sano fino al prossimo controllo.

Questo failover viene gestito internamente dall'SDK e assicura che le richieste evitino partizioni problematiche note fino a quando non vengono confermate nuovamente integre.

Configurazione tramite variabili di ambiente

È possibile controllare il comportamento PPCB usando queste variabili di ambiente:

Variabile Descrizione Impostazione predefinita
AZURE_COSMOS_ENABLE_CIRCUIT_BREAKER Abilita/disabilita PPCB false
AZURE_COSMOS_CONSECUTIVE_ERROR_COUNT_TOLERATED_FOR_READ Numero massimo di errori di lettura consecutivi prima di contrassegnare una partizione non disponibile 10
AZURE_COSMOS_CONSECUTIVE_ERROR_COUNT_TOLERATED_FOR_WRITE Numero massimo di errori di scrittura consecutivi prima di contrassegnare una partizione non disponibile 5
AZURE_COSMOS_FAILURE_PERCENTAGE_TOLERATED Soglia percentuale di errore prima di contrassegnare una partizione non disponibile 90

Suggerimento

Le opzioni di configurazione aggiuntive possono essere esposte nelle versioni future per ottimizzare le durate di timeout e il comportamento di backoff di ripristino.

Aree geografiche escluse

La funzionalità delle aree escluse consente un controllo granulare sul routing delle richieste consentendo di escludere aree specifiche dalle località preferite in base alle richieste. Questa funzionalità è disponibile in Azure Cosmos DB Python SDK versione 4.14.0 e successive.

Vantaggi principali:

  • Gestire la limitazione della frequenza: quando si riscontrano risposte 429 (troppe richieste), instradare automaticamente le richieste alle aree alternative con la velocità effettiva disponibile
  • Routing di destinazione: assicurarsi che le richieste vengano gestite da aree specifiche escludendo tutte le altre
  • Ignorare l'ordine preferito: eseguire l'override dell'elenco delle aree preferite predefinite per le singole richieste senza creare client separati

Configurazione:

Le aree escluse possono essere configurate sia a livello di client che di richiesta:

from azure.cosmos import CosmosClient
from azure.cosmos.partition_key import PartitionKey

# Configure preferred locations and excluded locations at client level
preferred_locations = ['West US 3', 'West US', 'East US 2']
excluded_locations_on_client = ['West US 3', 'West US']

client = CosmosClient(
    url=HOST,
    credential=MASTER_KEY,
    preferred_locations=preferred_locations,
    excluded_locations=excluded_locations_on_client
)

database = client.create_database('TestDB')
container = database.create_container(
    id='TestContainer',
    partition_key=PartitionKey(path="/pk")
)

# Create an item (writes ignore excluded_locations in single-region write accounts)
test_item = {
    'id': 'Item_1',
    'pk': 'PartitionKey_1',
    'test_object': True,
    'lastName': 'Smith'
}
created_item = container.create_item(test_item)

# Read operations will use preferred_locations minus excluded_locations
# In this example: ['West US 3', 'West US', 'East US 2'] - ['West US 3', 'West US'] = ['East US 2']
item = container.read_item(
    item=created_item['id'],
    partition_key=created_item['pk']
)

Aree escluse a livello di richiesta:

Le aree escluse a livello di richiesta hanno la priorità più alta e sostituiscono le impostazioni a livello di client.

# Excluded locations can be specified per request, overriding client settings
excluded_locations_on_request = ['West US 3']

# Create item with request-level excluded regions
created_item = container.create_item(
    test_item,
    excluded_locations=excluded_locations_on_request
)

# Read with request-level excluded regions
# This will use: ['West US 3', 'West US', 'East US 2'] - ['West US 3'] = ['West US', 'East US 2']
item = container.read_item(
    item=created_item['id'],
    partition_key=created_item['pk'],
    excluded_locations=excluded_locations_on_request
)

Ottimizzazione della coerenza e della disponibilità

La funzionalità delle aree escluse offre un meccanismo aggiuntivo per bilanciare i compromessi tra coerenza e disponibilità nell'applicazione. Questa funzionalità è particolarmente utile negli scenari dinamici in cui i requisiti possono cambiare in base alle condizioni operative:

Gestione dinamica dell'interruzione: quando si verifica un'interruzione di un'area primaria e le soglie di interruzione del circuito a livello di partizione non sono sufficienti, le aree escluse abilitano il failover immediato senza modifiche al codice o riavvii dell'applicazione. In questo modo si ottiene una risposta più rapida ai problemi a livello di area rispetto all'attesa dell'attivazione automatica dell'interruttore.

Preferenze di coerenza condizionale: le applicazioni possono implementare strategie di coerenza diverse in base allo stato operativo:

  • Stato stabile: classificare in ordine di priorità le letture coerenti escludendo tutte le aree ad eccezione del database primario, garantendo la coerenza dei dati al costo potenziale della disponibilità
  • Scenari di interruzione: favorire la disponibilità rispetto alla coerenza rigorosa consentendo il routing tra aree, accettando potenziale ritardo dei dati in cambio della disponibilità continua del servizio

Questo approccio consente a meccanismi esterni, ad esempio gestori di traffico o servizi di bilanciamento del carico, di orchestrare le decisioni di failover mentre l'applicazione mantiene il controllo sui requisiti di coerenza tramite i modelli di esclusione dell'area.

Quando vengono escluse tutte le aree, le richieste verranno instradate all'area primaria/hub. Questa funzionalità funziona con tutti i tipi di richiesta, incluse le query ed è particolarmente utile per gestire le istanze client singleton, ottenendo al tempo stesso un comportamento di routing flessibile.

Uso dell'SDK

  • Installare l'SDK più recente

Agli SDK di Azure Cosmos DB vengono apportati continui miglioramenti per offrire prestazioni ottimali. Vedere le note sulla versione di Azure Cosmos DB SDK per determinare l'SDK più recente ed esaminare i miglioramenti.

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

Ogni istanza del client Azure Cosmos DB è thread-safe ed esegue la gestione efficiente delle connessioni e la memorizzazione nella cache degli indirizzi. Per consentire una gestione efficiente delle connessioni e prestazioni migliori da parte del client Azure Cosmos DB, è consigliabile usare una singola istanza del client Azure Cosmos DB per l'intera durata dell'applicazione.

  • Ottimizzare il timeout e ripetere le configurazioni

Le configurazioni di timeout e i criteri di ripetizione dei tentativi possono essere personalizzati in base alle esigenze dell'applicazione. Fare riferimento al documento timeout e ritentare la configurazione per ottenere un elenco completo delle configurazioni che è possibile personalizzare.

  • Usare il livello di coerenza minimo richiesto per l'applicazione

Quando si crea un CosmosClient, viene usata la coerenza a livello di account se non è specificato alcun elemento nella creazione del client. Per altre informazioni sui livelli di coerenza, vedere il documentoLivelli di coerenza.

  • Aumentare il carico di lavoro client

Se si sta eseguendo il test a livelli di velocità effettiva elevati, l'applicazione client può 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.

Una regola empirica efficace è quella di non superare del valore >50% l'utilizzo della CPU su un determinato server, per mantenere bassa la latenza.

  • Limite di risorse per i file aperti del sistema operativo

Alcuni sistemi Linux (ad esempio Red Hat) prevedono un limite massimo per il numero di file aperti e quindi per il numero totale di connessioni. Eseguire il comando seguente per visualizzare i limiti correnti:

ulimit -a

Il numero di file aperti (nofile) deve essere sufficientemente grande da disporre di spazio sufficiente per le dimensioni del pool di connessioni configurate e per altri file aperti dal sistema operativo. Può essere modificato per consentire dimensioni del pool di connessioni più grandi.

Aprire il file limits.conf:

vim /etc/security/limits.conf

Aggiungere/modificare le righe seguenti:

* - nofile 100000

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 di specificare i percorsi dei documenti da includere o escludere dall'indicizzazione sfruttando i percorsi di indicizzazione (setIncludedPaths e setExcludedPaths). L'uso dei percorsi di indicizzazione può consentire di ottenere prestazioni migliori e di ridurre le risorse di archiviazione dell'indice per gli scenari in cui i modelli di query sono noti in anticipo, poiché i costi dell'indicizzazione sono correlati direttamente al numero di percorsi univoci indicizzati. Il codice seguente, ad esempio, mostra come includere ed escludere dall'indicizzazione intere sezioni di documenti (note anche come sottoalbero) usando il carattere jolly "*".

container_id = "excluded_path_container"
indexing_policy = {
        "includedPaths" : [ {'path' : "/*"} ],
        "excludedPaths" : [ {'path' : "/non_indexed_content/*"} ]
        }
db.create_container(
    id=container_id,
    indexing_policy=indexing_policy,
    partition_key=PartitionKey(path="/pk"))

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

Velocità effettiva

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

Azure Cosmos DB offre un'ampia gamma di operazioni di database, incluse le query relazionali e gerarchiche con funzioni definite dall'utente, 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 occuparsi della pianificazione e della gestione delle risorse hardware, sarà possibile usare un'unità di richiesta come misura singola per le risorse necessarie per eseguire diverse operazioni di database e rispondere a una richiesta dell'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à di richiesta aggiuntive.

La complessità di una query influisce sulla quantità di unità richiesta usate per un'operazione. Il numero di predicati, la natura dei predicati, il numero di funzioni definite dall'utente 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 qualsiasi operazione (create, update o delete), esaminare l'intestazione x-ms-request-charge per determinare il numero di unità richiesta usate da queste operazioni.

document_definition = {
    'id': 'document',
    'key': 'value',
    'pk': 'pk'
}
document = container.create_item(
    body=document_definition,
)
print("Request charge is : ", container.client_connection.last_response_headers['x-ms-request-charge'])

L'addebito richiesta restituito in questa intestazione è una frazione della velocità effettiva con provisioning. Se, ad esempio, sono presenti 2000 UR/secondo e se la query precedente restituisce 1000 documenti da 1 kB, il costo dell'operazione è 1000. 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 termina preventivamente la richiesta con RequestRateTooLarge (codice di stato HTTP 429) e restituisce l'intestazione x-ms-retry-after-ms, che indica la quantità di tempo, in millisecondi, che l'utente deve attendere prima di eseguire di nuovo 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 più client operano cumulativamente in modo costante al di sopra della frequenza delle richieste, il numero di ripetizioni dei tentativi predefinito attualmente impostato su 9 internamente dal client potrebbe non essere sufficiente. In questo caso, il client genererà un'eccezione CosmosHttpResponseError con codice di stato 429 per l'applicazione. È possibile modificare il numero di tentativi predefinito passando la configurazioneretry_total al client. Per impostazione predefinita, l'eccezione CosmosHttpResponseError 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. Ciò 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.

Benché il comportamento automatizzato per la ripetizione dei tentativi consenta di migliorare la resilienza e l'usabilità per la maggior parte delle applicazioni, è possibile che provochi conflitti durante l'esecuzione dei benchmark delle prestazioni, in particolare durante la misurazione della 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.

  • Progettare documenti di dimensioni minori per ottenere una velocità effettiva maggiore

L'addebito per le richieste, ovvero il costo di elaborazione delle richieste, per un'operazione specifica è correlato direttamente alle dimensioni del documento. Le operazioni sui documenti di grandi dimensioni sono più costose rispetto alle operazioni per i documenti di piccole dimensioni. In teoria, l'applicazione e i flussi di lavoro devono essere progettati in modo che la dimensione dell'elemento sia pari a ~1 kB o di un ordine di grandezza simile. Per le applicazioni sensibili alla latenza è consigliabile evitare elementi di grandi dimensioni. I documenti di più MB rallenteranno l'applicazione.

Passaggi successivi

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

  • Last updated on