Sdílet prostřednictvím

Osvědčené postupy pro sadu .NET SDK služby Azure Cosmos DB

  • Článek

PLATÍ PRO: NoSQL

Tento článek vás provede osvědčenými postupy pro používání sady .NET SDK služby Azure Cosmos DB. Následující postupy vám pomůžou zlepšit latenci, dostupnost a zvýšit celkový výkon.

Další informace o používání sady .NET SDK od inženýra služby Azure Cosmos DB najdete v následujícím videu.

Kontrolní seznam

Zkontrolováno Předmět Podrobnosti nebo odkazy
Verze sady SDK Vždy používejte nejnovější verzi sady SDK služby Azure Cosmos DB, která je k dispozici pro optimální výkon.
Klient Singleton Pro zajištění lepšího výkonu použijte jednu instanci CosmosClient po celou dobu životnosti aplikace.
Oblasti Nezapomeňte aplikaci spustit ve stejné oblasti Azure jako účet služby Azure Cosmos DB, kdykoli je to možné, abyste snížili latenci. Povolte 2 až 4 oblasti a replikujte své účty do více oblastí, aby byla nejlepší dostupnost. U produkčních úloh povolte převzetí služeb při selhání spravované službou. V případě absence této konfigurace dojde ke ztrátě dostupnosti zápisu po celou dobu výpadku oblasti zápisu, protože ruční převzetí služeb při selhání nebude úspěšné kvůli nedostatku připojení k oblasti. Informace o tom, jak přidat více oblastí pomocí sady .NET SDK, najdete tady.
Dostupnost a převzetí služeb při selhání Nastavte ApplicationPreferredRegions nebo ApplicationRegion v sadě SDK v3 a preferredLocations v sadě SDK v2 pomocí seznamu upřednostňovaných oblastí. Během převzetí služeb při selhání se operace zápisu posílají do aktuální oblasti zápisu a všechna čtení se odesílají do první oblasti v seznamu upřednostňovaných oblastí. Další informace o místní mechanikě převzetí služeb při selhání najdete v průvodci odstraňováním potíží s dostupností.
Procesor Kvůli nedostatku prostředků na klientském počítači můžete narazit na problémy s připojením nebo dostupností. Monitorujte využití procesoru na uzlech, na kterých běží klient Služby Azure Cosmos DB, a pokud je využití vysoké, vertikálně navyšte nebo navyšte kapacitu.
Hostování Pokud je to možné, používejte 64bitové zpracování hostitele s Windows pro zajištění nejlepšího výkonu. V případě produkčních úloh citlivých na latenci v režimu s přímým režimem důrazně doporučujeme používat alespoň 4 jádra a 8GB virtuální počítače s pamětí, kdykoli je to možné.
Režimy připojení Pro zajištění nejlepšího výkonu použijte přímý režim . Pokyny k tomuto postupu najdete v dokumentaci k sadě SDK V3 nebo dokumentaci k sadě SDK V2.
Sítě Pokud ke spuštění aplikace používáte virtuální počítač, povolte na virtuálním počítači akcelerované síťové služby , aby pomohly s kritickými body kvůli vysokému provozu a snížila latenci nebo zpoždění procesoru. Můžete také zvážit použití vyššího koncového virtuálního počítače, ve kterém je maximální využití procesoru nižší než 70 %.
Dočasné vyčerpání portů Pro řídké nebo sporadické spojení jsme nastavili IdleConnectionTimeout a PortReuseMode na PrivatePortPool. Tato IdleConnectionTimeout vlastnost pomáhá řídit čas, po kterém jsou nevyužitá připojení uzavřena. Tím se sníží počet nepoužívaných připojení. Ve výchozím nastavení jsou nečinná připojení trvale otevřená. Sada hodnot musí být větší nebo rovna 10 minut. Doporučujeme hodnoty mezi 20 minutami a 24 hodinami. Tato PortReuseMode vlastnost umožňuje sadě SDK používat malý fond dočasných portů pro různé cílové koncové body služby Azure Cosmos DB.
Použití Async/Await Vyhněte se blokování volání: Task.Result, Task.Waita Task.GetAwaiter().GetResult(). Celý zásobník volání je asynchronní, aby bylo možné využívat vzory async/await . Mnoho synchronních blokujících volání vede k hladovění fondu vláken a snížení doby odezvy.
Koncové časové limity Pokud chcete získat koncové časové limity, musíte použít parametry RequestTimeout i CancellationToken parametry. Další podrobnosti najdete v průvodci odstraňováním potíží s časovým limitem.
Logika opakování Další informace o chybách, které se mají opakovat a které sady SDK opakují, najdete v průvodci návrhem. U účtů nakonfigurovaných s více oblastmi existují některé scénáře, ve kterých se sada SDK bude automaticky opakovat v jiných oblastech. Podrobnosti implementace specifické pro .NET najdete ve zdrojovém úložišti sady SDK.
Ukládání názvů databází nebo kolekcí do mezipaměti Načtěte názvy databází a kontejnerů z konfigurace nebo je při spuštění ukážíte do mezipaměti. Volání jako ReadDatabaseAsync nebo ReadDocumentCollectionAsync nebo CreateDatabaseQuery budou CreateDocumentCollectionQuery mít za následek volání metadat do služby, která spotřebovávají limit ru rezervovaných systémem. CreateIfNotExist pro nastavení databáze by se měla používat pouze jednou. Celkově by se tyto operace měly provádět zřídka.
Hromadná podpora Ve scénářích, kdy možná nebudete muset optimalizovat latenci, doporučujeme povolit hromadnou podporu pro ukládání velkých objemů dat.
Paralelní dotazy Sada SDK služby Azure Cosmos DB podporuje paralelní spouštění dotazů, aby se zlepšila latence a propustnost dotazů. Doporučujeme nastavit MaxConcurrency vlastnost v rámci QueryRequestsOptions počtu oddílů, které máte. Pokud nevíte o počtu oddílů, začněte tím, že použijete int.MaxValue, což vám poskytne nejlepší latenci. Pak snižte počet, dokud nebude vyhovovat omezením prostředků prostředí, aby nedocházelo k problémům s vysokým využitím procesoru. Nastavte MaxBufferedItemCount také očekávaný počet vrácených výsledků, abyste omezili počet předem načtených výsledků.
Backoffy testování výkonu Při testování aplikace byste měli implementovat backoffy v RetryAfter intervalech. Dodržování zpětného ukončení pomáhá zajistit, abyste strávili minimální dobu čekáním mezi opakovanými pokusy.
Indexování Zásady indexování služby Azure Cosmos DB také umožňují určit, které cesty k dokumentu se mají zahrnout nebo vyloučit z indexování pomocí cest indexování (IndexingPolicy.IncludedPaths a IndexingPolicy.ExcludedPaths). Zajistěte, abyste vyloučili nepoužívané cesty z indexování pro rychlejší zápisy. Další informace o tom, jak vytvářet indexy pomocí sady SDK, najdete v tématu Tipy pro zvýšení výkonu sady .NET SDK v3.
Velikost dokumentu Poplatek za požadavek zadané operace koreluje přímo s velikostí dokumentu. Doporučujeme zmenšit velikost dokumentů, protože operace s velkými dokumenty stojí více než operace s menšími dokumenty.
Zvýšení počtu vláken nebo úloh Vzhledem k tomu, že volání do služby Azure Cosmos DB se provádějí přes síť, může být potřeba měnit stupeň souběžnosti vašich požadavků, aby klientská aplikace strávila minimální dobu čekáním mezi požadavky. Pokud například používáte paralelní knihovnu úloh .NET, vytvořte pořadí stovek úloh, které čtou nebo zapisují do služby Azure Cosmos DB.
Povolení metrik dotazů Pokud chcete více protokolování provádění back-endových dotazů, můžete povolit metriky dotazů SQL pomocí naší sady .NET SDK. Další informace o tom, jak shromažďovat metriky dotazů SQL, najdete v tématu metriky a výkon dotazů.
Protokolování sady SDK Diagnostika sady Log SDK pro nevyřízených scénářů, jako jsou výjimky nebo kdy požadavky překračují očekávanou latenci.
DefaultTraceListener DefaultTraceListener představuje problémy s výkonem v produkčních prostředích, což způsobuje vysoké kritické body procesoru a vstupně-výstupních operací. Ujistěte se, že používáte nejnovější verze sady SDK, nebo ze své aplikace odeberte defaultTraceListener.
Nepoužívejte žádné speciální znaky v identifikátorech. Některé znaky jsou omezené a nelze je použít v některých identifikátorech: /, \, ?, #. Obecné doporučení je nepoužívat žádné speciální znaky v identifikátorech, jako je název databáze, název kolekce, ID položky nebo klíč oddílu, aby nedocházelo k neočekávanému chování.

Zachytávání diagnostiky

Všechny odpovědi v sadě SDK, včetně CosmosException, mají Diagnostics vlastnost. Tato vlastnost zaznamenává všechny informace související s jedním požadavkem, včetně toho, jestli došlo k opakovaným pokusům nebo přechodným selháním.

Diagnostika se vrátí jako řetězec. Řetězec se mění s každou verzí, protože se vylepšuje pro řešení potíží s různými scénáři. U každé verze sady SDK bude řetězec obsahovat zásadní změny formátování. Řetězec neza parsujte, abyste se vyhnuli zásadním změnám. Následující ukázka kódu ukazuje, jak číst diagnostické protokoly pomocí sady .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()
}

Osvědčené postupy pro připojení HTTP

Sada .NET SDK používá HttpClient k provádění požadavků HTTP bez ohledu na nakonfigurovaný režim připojení. Protokol HTTP v přímém režimu se používá pro operace metadat a v režimu brány se používá pro operace roviny dat i metadat. Jedním ze základních principů HttpClient je zajistit HttpClient , aby mohl reagovat na změny DNS ve vašem účtu přizpůsobením doby života připojení ve fondu. Pokud jsou připojení ve fondu otevřená, nereagují na změny DNS. Toto nastavení vynutí pravidelné zavření připojení ve fondu a zajistí, aby vaše aplikace reagovala na změny DNS. Naše doporučení je, že tuto hodnotu přizpůsobíte podle svého režimu připojení a úlohy, abyste vyvážit dopad na výkon často vytvářených nových připojení a museli reagovat na změny DNS (dostupnost). 5minutová hodnota by byla dobrým startem, která se dá zvýšit, pokud má vliv zejména na výkon v režimu brány.

Vlastního klienta HttpClient můžete vložit například takto CosmosClientOptions.HttpClientFactory:

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

Pokud používáte injektáž závislostí .NET, můžete proces Singleton zjednodušit:

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

Osvědčené postupy při používání režimu brány

Pokud používáte režim brány, zvyšte System.Net MaxConnections počet hostitelů. Požadavky služby Azure Cosmos DB se provádějí přes PROTOKOL HTTPS/REST při použití režimu brány. Podléhají výchozímu limitu připojení na název hostitele nebo IP adresu. Možná budete muset nastavit MaxConnections vyšší hodnotu (od 100 do 1 000), aby klientská knihovna mohla používat více souběžných připojení ke službě Azure Cosmos DB. V sadě .NET SDK 1.8.0 a novějších je výchozí hodnota ServicePointManager.DefaultConnectionLimit 50. Pokud chcete hodnotu změnit, můžete ji nastavit CosmosClientOptions.GatewayModeMaxConnectionLimit na vyšší hodnotu.

Osvědčené postupy pro úlohy náročné na zápis

U úloh, které mají velké objemy datových částí, nastavte EnableContentResponseOnWrite možnost požadavku na falsehodnotu . Služba už nebude do sady SDK vracet vytvořený nebo aktualizovaný prostředek. Za normálních okolností, protože aplikace má vytvořený objekt, nepotřebuje službu k vrácení. Hodnoty hlaviček jsou stále přístupné, například poplatky za požadavek. Zakázání odpovědi na obsah může přispět ke zlepšení výkonu, protože sada SDK už nemusí přidělovat paměť nebo serializovat tělo odpovědi. Snižuje také využití šířky pásma sítě, aby se dále pomohl výkon.

Důležité

Nastavením EnableContentResponseOnWrite se false také zakáže odpověď z operace triggeru.

Osvědčené postupy pro aplikace s více tenanty

Aplikace, které distribuují využití mezi více tenantů, ve kterých je každý tenant reprezentován jinou databází, kontejnerem nebo klíčem oddílu ve stejném účtu služby Azure Cosmos DB, by měly používat jednu instanci klienta. Jedna instance klienta může interagovat se všemi databázemi, kontejnery a klíči oddílů v rámci účtu a je osvědčeným postupem použít jeden vzor.

Pokud je ale každý tenant reprezentovaný jiným účtem služby Azure Cosmos DB, je potřeba vytvořit samostatnou instanci klienta pro každý účet. Jeden vzor stále platí pro každého klienta (jeden klient pro každý účet po celou dobu životnosti aplikace), ale pokud je objem tenantů vysoký, může být obtížné spravovat počet klientů. Připojení můžou zvýšit limity výpočetního prostředí a způsobit problémy s připojením.

V těchto případech se doporučuje:

  • Seznamte se s omezeními výpočetního prostředí (prostředky procesoru a připojení). Pokud je to možné, doporučujeme používat virtuální počítače s alespoň 4 jádry a 8 GB paměti.
  • Na základě omezení výpočetního prostředí určete počet instancí klienta (a proto počet tenantů), které dokáže zpracovat jedna výpočetní instance. Počet připojení, která se otevřou na klienta, můžete odhadnout v závislosti na zvoleném režimu připojení.
  • Vyhodnoťte distribuci tenantů napříč instancemi. Pokud každá výpočetní instance dokáže úspěšně zpracovat určité omezené množství tenantů, vyrovnávání zatížení a směrování tenantů do různých výpočetních instancí by umožnilo škálování s rostoucím počtem tenantů.
  • U řídkých úloh zvažte použití mezipaměti Nejméně často používané jako struktury k uložení instancí klienta a vyřazení klientů pro klienty, kteří nebyli během časového intervalu přístupní. Jednou z možností v .NET je MemoryCacheEntryOptions, kde RegisterPostEvictionCallback lze použít k vyřazení neaktivních klientů a SetSlidingExpiration lze použít k definování maximální doby uchovávání neaktivních připojení.
  • Vyhodnoťte použití režimu brány, abyste snížili počet síťových připojení.
  • Při použití režimu Direct zvažte úpravu CosmosClientOptions.IdleTcpConnectionTimeout a CosmosClientOptions.PortReuseMode v konfiguraci přímého režimu tak, aby se zavřela nepoužitá připojení a zachovala objem připojení pod kontrolou.

Další kroky

Ukázkovou aplikaci, která se používá k vyhodnocení služby Azure Cosmos DB pro vysoce výkonné scénáře na několika klientských počítačích, najdete v tématu Testování výkonu a škálování pomocí služby Azure Cosmos DB.

Další informace o návrhu aplikace pro škálování a vysoký výkon najdete v tématu Dělení a škálování ve službě Azure Cosmos DB.

Pokoušíte se naplánovat kapacitu migrace do služby Azure Cosmos DB? Informace o stávajícím databázovém clusteru můžete použít k plánování kapacity.