Ajánlott eljárások az Azure Cosmos DB .NET SDK-hoz

  • Cikk

A KÖVETKEZŐKRE VONATKOZIK: NoSQL

Ez a cikk az Azure Cosmos DB .NET SDK használatának ajánlott eljárásait ismerteti. A fenti eljárások követésének segítségével javíthatja a késést, a rendelkezésre állást és növelheti az általános teljesítményt.

Az alábbi videóból többet is megtudhat az Azure Cosmos DB-mérnök .NET SDK-jának használatáról.

Ellenőrzőlista

Jelölje be Tárgy Részletek/hivatkozások
SDK verziója Mindig az optimális teljesítmény érdekében elérhető Azure Cosmos DB SDK legújabb verzióját használja.
Egyszeri ügyfél Használjon egyetlen példánytCosmosClient az alkalmazás teljes élettartama alatt a jobb teljesítmény érdekében.
Régiók Ha lehetséges, a késés csökkentése érdekében mindenképpen ugyanabban az Azure-régióban futtassa az alkalmazást, mint az Azure Cosmos DB-fiókját. Engedélyezzen 2–4 régiót, és replikálja a fiókjait több régióban a legjobb rendelkezésre állás érdekében. Éles számítási feladatok esetén engedélyezze a szolgáltatás által felügyelt feladatátvételt. Ennek a konfigurációnak a hiányában a fiók írási rendelkezésre állása az írási régió kimaradásának teljes időtartama alatt megszakad, mivel a manuális feladatátvétel a régiókapcsolat hiánya miatt nem fog sikerülni. Ha többet szeretne megtudni arról, hogyan adhat hozzá több régiót a .NET SDK használatával, látogasson el ide
Rendelkezésre állás és feladatátvételek Állítsa be az ApplicationPreferredRegions vagy az ApplicationRegion értéket a v3 SDK-ban, és a PreferredLocations értéket a v2 SDK-ban az előnyben részesített régiók listájával. A feladatátvétel során a rendszer az írási műveleteket az aktuális írási régióba küldi, és az összes olvasást az előnyben részesített régiók listájában szereplő első régióba küldi. A regionális feladatátvételi mechanikával kapcsolatos további információkért tekintse meg a rendelkezésre állási hibaelhárítási útmutatót.
CPU Előfordulhat, hogy kapcsolódási/rendelkezésre állási problémákba ütközik az ügyfélszámítógép erőforrásainak hiánya miatt. Monitorozza a processzorkihasználtságot az Azure Cosmos DB-ügyfelet futtató csomópontokon, és ha a használat magas, vertikálisan fel- és leskálázható.
Üzemeltetés Amikor csak lehetséges, használja a Windows 64 bites gazdagépfeldolgozást a legjobb teljesítmény érdekében. A közvetlen módú, késésre érzékeny éles számítási feladatok esetében javasoljuk, hogy lehetőség szerint használjon legalább 4 magos és 8 GB memóriájú virtuális gépeket.
Kapcsolódási módok A legjobb teljesítmény érdekében használja a Közvetlen módot . Ennek módjáról a V3 SDK dokumentációjában vagy a V2 SDK dokumentációjában talál útmutatást.
Hálózatkezelés Ha virtuális gépet használ az alkalmazás futtatásához, engedélyezze a gyorsított hálózatkezelést a virtuális gépen, hogy segítsen a nagy forgalom miatti szűk keresztmetszetekben, és csökkentse a késést vagy a PROCESSZOR-jittert. Érdemes lehet egy magasabb szintű virtuális gépet is használni, ahol a maximális processzorhasználat 70% alatt van.
Rövid élettartamú portfogyás Ritka vagy szórványos kapcsolatok esetén a és PortReuseMode a IdleConnectionTimeout értékre PrivatePortPoolvan állítva. A IdleConnectionTimeout tulajdonság segít szabályozni azt az időt, amely után a nem használt kapcsolatok lezárulnak. Ez csökkenti a nem használt kapcsolatok számát. Alapértelmezés szerint a tétlen kapcsolatok határozatlan ideig nyitva maradnak. A beállított értéknek 10 percnél nagyobbnak vagy egyenlőnek kell lennie. 20 perc és 24 óra közötti értékeket ajánlottunk. A PortReuseMode tulajdonság lehetővé teszi, hogy az SDK rövid élettartamú portkészletet használjon a különböző Azure Cosmos DB-célvégpontokhoz.
Az Async/Await használata Kerülje a következő hívások blokkolását: Task.Result, Task.Waités Task.GetAwaiter().GetResult(). A teljes hívásverem aszinkron, hogy kihasználhassa az aszinkron/várakozási minták előnyeit. Számos szinkron blokkoló hívás a szálkészlet éhezéséhez és a válaszidő romlásához vezet.
Végpontok közötti időtúllépések A végpontok közötti időtúllépésekhez mindkét RequestTimeout paramétert CancellationToken használnia kell. További részletekért tekintse meg az időtúllépési hibaelhárítási útmutatót.
Újrapróbálkozás logikája Az újrapróbálkozások hibáiról és az SDK-k által újrapróbálkozott hibákról a tervezési útmutatóban talál további információt. A több régióval konfigurált fiókok esetében vannak olyan esetek , amikor az SDK automatikusan újrapróbálkozott más régiókkal. A .NET-specifikus implementáció részleteiért látogasson el az SDK forrásadattárába.
Adatbázis-/gyűjteménynevek gyorsítótárazása Kérje le az adatbázisok és tárolók nevét a konfigurációból, vagy gyorsítótárazza őket az indításkor. A vagy hasonló ReadDatabaseAsync hívások CreateDatabaseQueryReadDocumentCollectionAsyncCreateDocumentCollectionQuery metaadat-hívásokat eredményeznek a szolgáltatás felé, amelyek a rendszer által fenntartott kérelemegység-korlátból származnak. CreateIfNotExist az adatbázis beállításához is csak egyszer kell használni. Általánosságban elmondható, hogy ezeket a műveleteket ritkán kell végrehajtani.
Tömeges támogatás Olyan esetekben, amikor nem kell optimalizálnia a késést, javasoljuk, hogy engedélyezze a tömeges támogatást a nagy mennyiségű adat memóriaképéhez.
Párhuzamos lekérdezések Az Azure Cosmos DB SDK támogatja a lekérdezések párhuzamos futtatását a lekérdezések jobb késése és átviteli sebessége érdekében. Javasoljuk, hogy állítsa a MaxConcurrency tulajdonságot a QueryRequestsOptions (z) értékre a partíciók számára. Ha nem ismeri a partíciók számát, kezdje a használatával int.MaxValue, amely a lehető legnagyobb késést biztosítja. Ezután csökkentse a számot, amíg meg nem felel a környezet erőforrás-korlátozásainak, hogy elkerülje a magas processzorhasználattal kapcsolatos problémákat. Emellett állítsa a MaxBufferedItemCount értéket a visszaadott eredmények várt számára, hogy korlátozza az előre beszúrt eredmények számát.
Teljesítménytesztelési visszalépések Amikor tesztelést végez az alkalmazáson, időközönként végre kell hajtania a visszalépéseket RetryAfter . A visszalépés figyelembevételével biztosíthatja, hogy az újrapróbálkozások között minimális ideig várakozhasson.
Indexelés Az Azure Cosmos DB indexelési szabályzata azt is lehetővé teszi, hogy az indexelési útvonalak (IndexingPolicy.IncludedPaths és IndexingPolicy.ExcludedPaths) használatával megszűrje, hogy mely dokumentumelérési utakat foglalja bele vagy zárja ki az indexelésből. A gyorsabb írás érdekében győződjön meg arról, hogy kizárja a nem használt elérési utakat az indexelésből. További információ az indexek SDK-val történő létrehozásáról: Teljesítménytippek .NET SDK v3.
Dokumentumméret Egy adott művelet kérelemdíja közvetlenül a dokumentum méretével korrelál. Javasoljuk, hogy csökkentse a dokumentumok méretét, mivel a nagyméretű dokumentumokon végzett műveletek többe kerülnek, mint a kisebb dokumentumokon végzett műveletek.
Szálak/tevékenységek számának növelése Mivel az Azure Cosmos DB-be irányuló hívások a hálózaton keresztül jönnek létre, előfordulhat, hogy módosítania kell a kérések párhuzamossági fokát, hogy az ügyfélalkalmazás minimális várakozási időt töltsön a kérések között. Ha például a .NET-feladat párhuzamos kódtárát használja, hozzon létre több száz olyan feladat sorrendjében, amelyek az Azure Cosmos DB-ből olvasnak vagy írnak.
Lekérdezési metrikák engedélyezése A háttérbeli lekérdezések végrehajtásának további naplózásához engedélyezheti az SQL-lekérdezési metrikákat a .NET SDK használatával. További információ az SQL-lekérdezési metrikák gyűjtéséről: lekérdezési metrikák és teljesítmény.
SDK-naplózás Naplózza az SDK-diagnosztikát a fennálló forgatókönyvekhez, például a kivételekhez, vagy ha a kérések túllépik a várt késést.
DefaultTraceListener A DefaultTraceListener teljesítményproblémákat okoz az éles környezetekben, ami magas processzor- és I/O-szűk keresztmetszeteket okoz. Győződjön meg arról, hogy a legújabb SDK-verziókat használja, vagy távolítsa el a DefaultTraceListenert az alkalmazásból
Ne használjon speciális karaktereket az azonosítókban Egyes karakterek korlátozottak, és egyes azonosítókban nem használhatók: '/', '\', '?', '#'. Általános javaslat, hogy ne használjon speciális karaktereket az azonosítókban, például az adatbázisnévben, a gyűjteménynévben, az elemazonosítóban vagy a partíciókulcsban a váratlan viselkedés elkerülése érdekében.

A diagnosztikai adatok rögzítése

Az SDK összes válasza , beleértve a tulajdonságot Diagnostics isCosmosException. Ez a tulajdonság az egyetlen kéréssel kapcsolatos összes információt rögzíti, beleértve az újrapróbálkozások vagy az átmeneti hibák esetlegességét is.

A rendszer sztringként adja vissza a diagnosztikát. A sztring az egyes verziókkal együtt változik, mivel a különböző forgatókönyvek hibaelhárításához továbbfejlesztettük. Az SDK minden verziójában a sztring formázása kompatibilitástörően változik. Ne elemezd a sztringet a kompatibilitástörő változások elkerülése érdekében. Az alábbi kódminta bemutatja, hogyan olvashatja be a diagnosztikai naplókat a .NET SDK használatával:

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()
}

Ajánlott eljárások HTTP-kapcsolatokhoz

A .NET SDK a konfigurált kapcsolati módtól függetlenül HTTP-kéréseket HttpClient hajt végre. A Közvetlen módban a HTTP metaadat-műveletekhez, átjáró módban pedig adatsík- és metaadat-műveletekhez is használható. A HttpClient egyik alapja annak biztosítása, hogy a rendszer képes legyen reagálni a HttpClient fiók DNS-változásaira a készletezett kapcsolat élettartamának testreszabásával. Amíg a készletezett kapcsolatok nyitva maradnak, nem reagálnak a DNS-változásokra. Ez a beállítás kényszeríti a készletezett kapcsolatok rendszeres bezárását , biztosítva, hogy az alkalmazás reagáljon a DNS-változásokra. Azt javasoljuk, hogy ezt az értéket a kapcsolati mód és a számítási feladat alapján szabja testre, hogy egyensúlyba hozza az új kapcsolatok gyakran létrejönő teljesítménybeli hatását, és reagálnia kell a DNS-változásokra (rendelkezésre állás). Az 5 perces érték jó kezdés lenne, amely növelhető, ha ez hatással van a teljesítményre, különösen az Átjáró mód esetében.

Az egyéni HttpClientet CosmosClientOptions.HttpClientFactorybeszúrhatja a segítségével, például:

// 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);

Ha .NET-függőséginjektálást használ, egyszerűbbé teheti a Singleton-folyamatot:

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);
});

Ajánlott eljárások átjáró mód használatakor

Növelje System.Net MaxConnections gazdagépenként az Átjáró mód használatakor. Az Azure Cosmos DB-kérések HTTPS/REST protokollon keresztül, átjáró mód használata esetén lesznek megadva. Gazdanév vagy IP-cím szerint az alapértelmezett kapcsolati korlát vonatkozik rájuk. Előfordulhat, hogy magasabb értéket kell beállítania MaxConnections (100 és 1000 között), hogy az ügyfélkódtár több egyidejű kapcsolatot használjon az Azure Cosmos DB-vel. A .NET SDK 1.8.0-s és újabb verzióiban az alapértelmezett érték ServicePointManager.DefaultConnectionLimit 50. Az érték módosításához magasabb értéket állíthat be CosmosClientOptions.GatewayModeMaxConnectionLimit .

Ajánlott eljárások írási nehéz számítási feladatokhoz

A nagy mennyiségű hasznos adatokkal rendelkező számítási feladatok esetében állítsa a kérelem beállítását a EnableContentResponseOnWrite következőre false: . A szolgáltatás többé nem adja vissza a létrehozott vagy frissített erőforrást az SDK-nak. Általában, mivel az alkalmazás rendelkezik a létrehozott objektummal, nem kell a szolgáltatásnak visszaadnia. A fejlécértékek továbbra is elérhetők, például egy kérelemdíj. A tartalomválasz letiltása javíthatja a teljesítményt, mivel az SDK-nak már nem kell memóriát lefoglalnia vagy szerializálnia a válasz törzsét. Emellett csökkenti a hálózati sávszélesség használatát is, hogy tovább segítse a teljesítményt.

Fontos

A beállítás EnableContentResponseOnWrite a false triggerművelet válaszát is letiltja.

Ajánlott eljárások több-bérlős alkalmazásokhoz

Azoknak az alkalmazásoknak, amelyek több bérlő között osztják el a használatot, ahol minden bérlőt egy másik adatbázis, tároló vagy partíciókulcs képvisel ugyanazon az Azure Cosmos DB-fiókon belül , egyetlen ügyfélpéldányt kell használniuk. Egyetlen ügyfélpéldány használhatja a fiókban található összes adatbázist, tárolót és partíciókulcsot, és ajánlott a singleton mintát használni.

Ha azonban minden bérlőt egy másik Azure Cosmos DB-fiók képvisel, fiókonként külön ügyfélpéldányt kell létrehoznia. A singleton minta továbbra is minden ügyfélre érvényes (az alkalmazás teljes élettartama alatt minden fiókhoz egy ügyfél), de ha a bérlők mennyisége magas, az ügyfelek száma nehézkes lehet. A kapcsolatok a számítási környezet korlátain túl is növekedhetnek, és csatlakozási problémákat okozhatnak.

Ezekben az esetekben a következőket javasoljuk:

  • A számítási környezet (CPU- és kapcsolati erőforrások) korlátainak megismerése. Javasoljuk, hogy ha lehetséges, legalább 4 magos és 8 GB memóriával rendelkező virtuális gépeket használjunk.
  • A számítási környezet korlátozásai alapján határozza meg, hogy hány ügyfélpéldányt (és ezáltal hány bérlőt) kezelhet egyetlen számítási példány. A kiválasztott kapcsolati módtól függően megbecsülheti az ügyfélenként megnyíló kapcsolatok számát.
  • Bérlők példányok közötti eloszlásának kiértékelése. Ha minden számítási példány sikeresen képes kezelni egy bizonyos korlátozott számú bérlőt, a bérlők terheléselosztása és a bérlők különböző számítási példányokhoz való átirányítása lehetővé tenné a skálázást a bérlők számának növekedésével.
  • A ritkán használt számítási feladatok esetében érdemes lehet a legkevésbé gyakran használt gyorsítótárat használni az ügyfélpéldányok tárolására és az olyan bérlők ügyfeleinek elidegenítésére, amelyekhez nem fértek hozzá az időkereten belül. A .NET-ben az egyik lehetőség a MemoryCacheEntryOptions, ahol a RegisterPostEvictionCallback az inaktív ügyfelek megsemmisítésére használható, a SetSlidingExpiration pedig az inaktív kapcsolatok maximális tárolásának időtartamának meghatározására használható.
  • Értékelje ki az átjárómódot a hálózati kapcsolatok számának csökkentése érdekében.
  • A Közvetlen mód használatakor érdemes módosítani a CosmosClientOptions.IdleTcpConnectionTimeout és a CosmosClientOptions.PortReuseMode beállítást a közvetlen mód konfigurációján a nem használt kapcsolatok bezárásához és a kapcsolatok mennyiségének szabályozásához.

Következő lépések

Az Azure Cosmos DB néhány ügyfélszámítógépen történő nagy teljesítményű forgatókönyveinek kiértékeléséhez használt mintaalkalmazásért lásd: Teljesítmény- és méretezési tesztelés az Azure Cosmos DB-vel.

Ha többet szeretne megtudni az alkalmazás méretezésre és nagy teljesítményre való tervezéséről, olvassa el a Particionálás és skálázás az Azure Cosmos DB-ben című témakört.

Kapacitástervezést szeretne végezni az Azure Cosmos DB-be való migráláshoz? A kapacitástervezéshez használhatja a meglévő adatbázisfürt adatait.