Metodtips för Azure Cosmos DB .NET SDK

  • Artikel

GÄLLER FÖR: NoSQL

Den här artikeln beskriver 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 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

Markerad Ä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 hela 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. Om den här konfigurationen saknas drabbas kontot av förlust av skrivtillgänglighet under hela avbrottstiden för skrivregionen, eftersom manuell redundans inte lyckas på grund av bristande regionanslutning. Mer information om hur du lägger till flera regioner med hjälp av .NET SDK finns 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 ditt program 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 kan också överväga att använda en virtuell dator med en 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 styra 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 att blockera anrop: Task.Result, Task.Waitoch Task.GetAwaiter().GetResult(). Hela anropsstacken är asynkron för att dra nytta av async/await-mönster . Många synkrona blockeringsanrop leder till att trådpoolen svälter och försämrar svarstiderna.
Tidsgränser från slutpunkt till slutpunkt För att få timeouter från slutpunkt till slutpunkt måste du använda parametrarna och RequestTimeoutCancellationToken . Mer information finns i vår felsökningsguide för timeout.
Logik för återförsök Mer information om vilka fel som ska försöka igen och vilka som SDK:er försöker utföra igen på nytt 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 från början. Anrop som ReadDatabaseAsync eller ReadDocumentCollectionAsync och CreateDatabaseQuery eller 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 mängder data.
Parallella frågor Azure Cosmos DB SDK stöder körning av frågor parallellt för bättre svarstid och dataflöde i dina frågor. Vi rekommenderar att du anger MaxConcurrency egenskapen inom QueryRequestsOptions till 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 bästa möjliga svarstid. Minska sedan antalet tills det passar resursbegränsningarna i miljön för att undvika problem med hög CPU-användning. MaxBufferedItemCount Ange också till det förväntade antalet resultat som returneras för att begränsa antalet förinställda resultat.
Backoffs för prestandatestning När du testar ditt program bör du implementera backoffs med RetryAfter jämna mellanrum. Att respektera backoffen hjälper dig att se till att du ägnar en 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 dina körningar av serverdelsfrågor kan du aktivera SQL-frågemått 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 ger upphov till prestandaproblem i produktionsmiljöer som orsakar hög 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:t, inklusive CosmosException, har en Diagnostics -egenskap. Den här egenskapen registrerar all information som är relaterad till 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 kommer strängen att ha 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 har konfigurerats. I direktläge används HTTP för metadataåtgärder och i gatewayläge används det 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 poolanslutningar att stängas regelbundet, vilket säkerställer att programmet 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 prestandaeffekten 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 gatewaylä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 när du använder 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. Rubrikvärdena är fortfarande tillgängliga, till exempel en begärandeavgift. Om du inaktiverar innehållssvaret kan du förbättra prestandan eftersom SDK inte längre behöver allokera minne eller serialisera brödtexten i svaret. 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 över flera klientorganisationer 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 enda 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 antalet klienter är hög kan antalet klienter vara svårt att hantera. Anslutningar kan öka utanför 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 (CPU- 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 beräkna antalet anslutningar som ska ö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 ofta 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 att lagra 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 göra kapacitetsplanering för en migrering till Azure Cosmos DB? Du kan använda information om ditt befintliga databaskluster för kapacitetsplanering.