Dela via

Metodtips för Azure Cosmos DB .NET SDK

  • Artikel

GÄLLER FÖR: NoSQL

Den här artikeln går igenom metodtipsen för att använda Azure Cosmos DB .NET SDK. Genom att följa dessa metoder kan du förbättra svarstiden, tillgängligheten och öka den övergripande prestandan.

Titta på videon nedan om du vill veta mer om hur du använder .NET SDK från en Azure Cosmos DB-tekniker!

Checklista

Kontrollerad Ämne Information/länkar
SDK-version Använd alltid den senaste versionen av Azure Cosmos DB SDK som är tillgänglig för optimala prestanda.
Singleton-klient Använd en enda instans av CosmosClient under programmets livslängd för bättre prestanda.
Regioner Se till att köra ditt program i samma Azure-region som ditt Azure Cosmos DB-konto när det är möjligt för att minska svarstiden. Aktivera 2–4 regioner och replikera dina konton i flera regioner för bästa tillgänglighet. Aktivera tjänsthanterad redundans för produktionsarbetsbelastningar. I avsaknad av den här konfigurationen kommer kontot att uppleva förlust av skrivtillgänglighet under hela skrivningsregionens avbrott, eftersom manuell redundans inte lyckas på grund av bristande regionanslutning. Om du vill veta hur du lägger till flera regioner med hjälp av .NET SDK besöker du här
Tillgänglighet och redundans Ange ApplicationPreferredRegions eller ApplicationRegion i v3 SDK och PreferredLocations i v2 SDK med hjälp av listan med önskade regioner. Under redundansväxlingar skickas skrivåtgärder till den aktuella skrivregionen och alla läsningar skickas till den första regionen i listan över önskade regioner. Mer information om regional redundansmekanik finns i felsökningsguiden för tillgänglighet.
Processor Du kan stöta på problem med anslutning/tillgänglighet på grund av brist på resurser på klientdatorn. Övervaka cpu-användningen på noder som kör Azure Cosmos DB-klienten och skala upp/ut om användningen är hög.
Värd Använd Windows 64-bitars värdbearbetning för bästa prestanda när det är möjligt. För fördröjningskänsliga produktionsarbetsbelastningar i direktläge rekommenderar vi starkt att du använder minst 4 kärnor och virtuella datorer med 8 GB minne när det är möjligt.
Anslutningslägen Använd direktläge för bästa prestanda. Anvisningar om hur du gör detta finns i V3 SDK-dokumentationen eller V2 SDK-dokumentationen.
Nätverk Om du använder en virtuell dator för att köra programmet aktiverar du Accelererat nätverk på den virtuella datorn för att hjälpa till med flaskhalsar på grund av hög trafik och minska svarstiden eller CPU-jitter. Du kanske också vill överväga att använda en virtuell dator med högre slutpunkt där den maximala CPU-användningen är under 70 %.
Tillfällig portöverbelastning För glesa eller sporadiska anslutningar anger IdleConnectionTimeout vi och PortReuseMode till PrivatePortPool. Egenskapen IdleConnectionTimeout hjälper till att kontrollera den tid efter vilken oanvända anslutningar stängs. Detta minskar antalet oanvända anslutningar. Som standard hålls inaktiva anslutningar öppna på obestämd tid. Värdeuppsättningen måste vara större än eller lika med 10 minuter. Vi rekommenderar värden mellan 20 minuter och 24 timmar. Med PortReuseMode egenskapen kan SDK:n använda en liten pool med tillfälliga portar för olika Azure Cosmos DB-målslutpunkter.
Använda Async/Await Undvik blockeringsanrop: Task.Result, Task.Waitoch Task.GetAwaiter().GetResult(). Hela anropsstacken är asynkron för att dra nytta av asynkrona/väntande mönster. Många synkrona blockeringsanrop leder till utsvulten trådpool och försämrade svarstider.
Tidsgränser från slutpunkt till slutpunkt För att få timeouter från slutpunkt till slutpunkt måste du använda både RequestTimeout och CancellationToken parametrar. Mer information finns i vår felsökningsguide för timeout.
Logik för omprövning Mer information om vilka fel som ska försöka igen och vilka som görs om av SDK:er finns i designguiden. För konton som har konfigurerats med flera regioner finns det vissa scenarier där SDK:t automatiskt försöker igen i andra regioner. Specifik implementeringsinformation för .NET finns på SDK-källlagringsplatsen.
Cachelagring av databas-/samlingsnamn Hämta namnen på dina databaser och containrar från konfigurationen eller cachelagrar dem vid start. Anrop som ReadDatabaseAsync eller ReadDocumentCollectionAsync och CreateDatabaseQuery CreateDocumentCollectionQuery resulterar i metadataanrop till tjänsten, som förbrukar från den systemreserverade RU-gränsen. CreateIfNotExist bör också endast användas en gång för att konfigurera databasen. Sammantaget bör dessa åtgärder utföras sällan.
Massstöd I scenarier där du kanske inte behöver optimera för svarstid rekommenderar vi att du aktiverar massstöd för dumpning av stora datavolymer.
Parallella frågor Azure Cosmos DB SDK stöder körning av frågor parallellt för bättre svarstid och dataflöde på dina frågor. Vi rekommenderar att du anger MaxConcurrency egenskapen inom QueryRequestsOptions det antal partitioner som du har. Om du inte känner till antalet partitioner börjar du med att använda int.MaxValue, vilket ger dig den bästa svarstiden. Minska sedan antalet tills det passar resursbegränsningarna i miljön för att undvika höga CPU-problem. Ange MaxBufferedItemCount också till det förväntade antalet resultat som returneras för att begränsa antalet fördefinierade resultat.
Backoffs för prestandatestning När du utför testning i ditt program bör du implementera backoffs med RetryAfter jämna mellanrum. Om du respekterar backoffen ser du till att du ägnar minimal tid åt att vänta mellan återförsöken.
Indexering Med Azure Cosmos DB-indexeringsprincipen kan du också ange vilka dokumentsökvägar som ska inkluderas eller undantas från indexering med hjälp av indexeringssökvägar (IndexingPolicy.IncludedPaths och IndexingPolicy.ExcludedPaths). Se till att du undantar oanvända sökvägar från indexering för snabbare skrivningar. Mer information om hur du skapar index med hjälp av SDK finns i prestandatips .NET SDK v3.
Dokumentstorlek Begärandeavgiften för en angiven åtgärd korrelerar direkt med dokumentets storlek. Vi rekommenderar att du minskar storleken på dina dokument eftersom åtgärder på stora dokument kostar mer än åtgärder på mindre dokument.
Öka antalet trådar/uppgifter Eftersom anrop till Azure Cosmos DB görs via nätverket kan du behöva variera graden av samtidighet för dina begäranden så att klientprogrammet ägnar minimal tid åt att vänta mellan begäranden. Om du till exempel använder .NET-aktivitetsparallellt bibliotek skapar du i ordningen hundratals aktiviteter som läser från eller skriver till Azure Cosmos DB.
Aktivera frågemått Om du vill ha mer loggning av körningen av serverdelsfrågan kan du aktivera SQL Query Metrics med hjälp av vår .NET SDK. Mer information om hur du samlar in SQL-frågemått finns i frågemått och prestanda.
SDK-loggning Logg-SDK-diagnostik för utestående scenarier, till exempel undantag eller när begäranden överskrider en förväntad svarstid.
DefaultTraceListener DefaultTraceListener medför prestandaproblem i produktionsmiljöer som orsakar höga cpu- och I/O-flaskhalsar. Kontrollera att du använder de senaste SDK-versionerna eller ta bort DefaultTraceListener från ditt program
Undvik att använda specialtecken i identifierare Vissa tecken är begränsade och kan inte användas i vissa identifierare: '/', '\', '?', '#'. Den allmänna rekommendationen är att inte använda några specialtecken i identifierare som databasnamn, samlingsnamn, objekt-ID eller partitionsnyckel för att undvika oväntade beteenden.

Samla in diagnostik

Alla svar i SDK, inklusive CosmosException, har en Diagnostics egenskap. Den här egenskapen registrerar all information som rör den enskilda begäran, inklusive om det fanns återförsök eller tillfälliga fel.

Diagnostiken returneras som en sträng. Strängen ändras med varje version eftersom den har förbättrats för felsökning av olika scenarier. Med varje version av SDK:t har strängen icke-bakåtkompatibla ändringar i formateringen. Parsa inte strängen för att undvika icke-bakåtkompatibla ändringar. Följande kodexempel visar hur du läser diagnostikloggar med hjälp av .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()
}

Metodtips för HTTP-anslutningar

.NET SDK använder HttpClient för att utföra HTTP-begäranden oavsett vilket anslutningsläge som konfigurerats. I direktläge används HTTP för metadataåtgärder och används i gatewayläge för både dataplans- och metadataåtgärder. En av grunderna i HttpClient är att se HttpClient till att kan reagera på DNS-ändringar på ditt konto genom att anpassa livslängden för poolanslutningen. Så länge poolanslutningar hålls öppna reagerar de inte på DNS-ändringar. Den här inställningen tvingar poolade anslutningar att stängas regelbundet, vilket säkerställer att ditt program reagerar på DNS-ändringar. Vår rekommendation är att du anpassar det här värdet enligt ditt anslutningsläge och din arbetsbelastning för att balansera prestandapåverkan av att ofta skapa nya anslutningar, med behov av att reagera på DNS-ändringar (tillgänglighet). Ett värde på 5 minuter skulle vara en bra start som kan ökas om det påverkar prestanda, särskilt för Gateway-läge.

Du kan mata in din anpassade HttpClient via CosmosClientOptions.HttpClientFactory, till exempel:

// Use a Singleton instance of the SocketsHttpHandler, which you can share across any HttpClient in your application
SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    // Pass your customized SocketHttpHandler to be used by the CosmosClient
    // Make sure `disposeHandler` is `false`
    HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
};

// Use a Singleton instance of the CosmosClient
return new CosmosClient("<connection-string>", cosmosClientOptions);

Om du använder .NET-beroendeinmatning kan du förenkla Singleton-processen:

SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);
// Registering the Singleton SocketsHttpHandler lets you reuse it across any HttpClient in your application
services.AddSingleton<SocketsHttpHandler>(socketsHttpHandler);

// Use a Singleton instance of the CosmosClient
services.AddSingleton<CosmosClient>(serviceProvider =>
{
    SocketsHttpHandler socketsHttpHandler = serviceProvider.GetRequiredService<SocketsHttpHandler>();
    CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
    {
        HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
    };

    return new CosmosClient("<connection-string>", cosmosClientOptions);
});

Metodtips vid användning av gatewayläge

Öka System.Net MaxConnections per värd när du använder gatewayläge. Azure Cosmos DB-begäranden görs via HTTPS/REST när du använder gatewayläge. De omfattas av standardanslutningsgränsen per värdnamn eller IP-adress. Du kan behöva ange MaxConnections ett högre värde (från 100 till 1 000) så att klientbiblioteket kan använda flera samtidiga anslutningar till Azure Cosmos DB. I .NET SDK 1.8.0 och senare är standardvärdet för ServicePointManager.DefaultConnectionLimit 50. Om du vill ändra värdet kan du ange CosmosClientOptions.GatewayModeMaxConnectionLimit ett högre värde.

Metodtips för skrivintensiva arbetsbelastningar

För arbetsbelastningar som har tunga nyttolaster anger du EnableContentResponseOnWrite alternativet för begäran till false. Tjänsten returnerar inte längre den skapade eller uppdaterade resursen till SDK:n. Eftersom programmet har objektet som skapas behöver det normalt inte tjänsten för att returnera det. Huvudvärdena är fortfarande tillgängliga, till exempel en begärandeavgift. Om du inaktiverar innehållssvaret kan du förbättra prestandan eftersom SDK:n inte längre behöver allokera minne eller serialisera svarets brödtext. Det minskar också användningen av nätverksbandbredd för att ytterligare hjälpa prestanda.

Viktigt!

Om du anger EnableContentResponseOnWrite till false inaktiveras även svaret från en utlösaråtgärd.

Metodtips för program med flera klientorganisationer

Program som distribuerar användning mellan flera klienter där varje klientorganisation representeras av en annan databas, container eller partitionsnyckel inom samma Azure Cosmos DB-konto bör använda en enda klientinstans. En enskild klientinstans kan interagera med alla databaser, containrar och partitionsnycklar i ett konto, och det är bästa praxis att använda singleton-mönstret.

Men när varje klientorganisation representeras av ett annat Azure Cosmos DB-konto måste du skapa en separat klientinstans per konto. Singleton-mönstret gäller fortfarande för varje klient (en klient för varje konto under programmets livslängd), men om mängden klienter är hög kan antalet klienter vara svårt att hantera. Anslutningar kan öka utöver gränserna för beräkningsmiljön och orsaka anslutningsproblem.

I dessa fall rekommenderar vi att du:

  • Förstå begränsningarna i beräkningsmiljön (PROCESSOR- och anslutningsresurser). Vi rekommenderar att du använder virtuella datorer med minst 4 kärnor och 8 GB minne när det är möjligt.
  • Baserat på begränsningarna i beräkningsmiljön avgör du antalet klientinstanser (och därmed antalet klienter) som en enda beräkningsinstans kan hantera. Du kan uppskatta antalet anslutningar som öppnas per klient beroende på vilket anslutningsläge som valts.
  • Utvärdera klientdistribution mellan instanser. Om varje beräkningsinstans kan hantera en viss begränsad mängd klienter skulle belastningsutjämning och routning av klienter till olika beräkningsinstanser möjliggöra skalning när antalet klienter växer.
  • För glesa arbetsbelastningar bör du överväga att använda ett cacheminne som används minst som struktur för att lagra klientinstanserna och ta bort klienter för klienter som inte har använts inom en tidsperiod. Ett alternativ i .NET är MemoryCacheEntryOptions, där RegisterPostEvictionCallback kan användas för att ta bort inaktiva klienter och SetSlidingExpiration kan användas för att definiera den maximala tiden för inaktiva anslutningar.
  • Utvärdera med gatewayläge för att minska antalet nätverksanslutningar.
  • När du använder direktläge bör du överväga att justera CosmosClientOptions.IdleTcpConnectionTimeout och CosmosClientOptions.PortReuseMode i direktlägeskonfigurationen för att stänga oanvända anslutningar och hålla volymen av anslutningar under kontroll.

Nästa steg

Ett exempelprogram som används för att utvärdera Azure Cosmos DB för scenarier med höga prestanda på några klientdatorer finns i Prestanda- och skalningstestning med Azure Cosmos DB.

Mer information om hur du utformar ditt program för skalning och höga prestanda finns i Partitionering och skalning i Azure Cosmos DB.

Försöker du planera kapacitet för en migrering till Azure Cosmos DB? Du kan använda information om ditt befintliga databaskluster för kapacitetsplanering.