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. Tyto postupy vám pomůžou zlepšit latenci, dostupnost a zvýšit celkový výkon.

Podívejte se na následující video, ve které se dozvíte další informace o používání sady .NET SDK od technika služby Azure Cosmos DB.

Kontrolní seznam

Zaškrtnuto Předmět Podrobnosti nebo odkazy
Verze SDK Pro zajištění optimálního výkonu vždy používejte nejnovější verzi sady SDK služby Azure Cosmos DB.
Jednoúčelový klient Pro zajištění lepšího výkonuCosmosClient používejte jednu instanci po celou dobu životnosti vaší aplikace.
Oblasti Pokud je to možné, nezapomeňte aplikaci spustit ve stejné oblasti Azure jako účet služby Azure Cosmos DB, aby se snížila latence. Povolte 2–4 oblasti a replikujte své účty do několika oblastí, abyste mohli mít nejlepší dostupnost. U produkčních úloh povolte převzetí služeb při selhání spravované službou. Při absenci této konfigurace dojde u účtu 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 chybějícímu 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 3 SDK a PreferredLocations v 2 SDK pomocí seznamu upřednostňovaných oblastí. Během převzetí služeb při selhání se operace zápisu odesí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ích mechanismech 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ůže dojít k problémům s připojením nebo dostupností. Monitorujte využití procesoru na uzlech, na kterých běží klient Služby Azure Cosmos DB, a v případě vysokého využití vertikálně navyšte nebo navyšte kapacitu.
Hostování Pokud je to možné, použijte 64bitové zpracování hostitelů s Windows pro zajištění nejlepšího výkonu. V případě produkčních úloh citlivých na latenci v přímém režimu důrazně doporučujeme používat virtuální počítače se 4 jádry a 8 GB paměti, 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 verze 3 nebo v dokumentaci k sadě SDK verze 2.
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 , které vám pomůžou s kritickými body způsobenými vysokým provozem a snížit latenci nebo kolísání procesoru. Můžete také zvážit použití virtuálního počítače vyššího konce, kde je maximální využití procesoru nižší než 70 %.
Vyčerpání dočasných portů Pro řídká nebo sporadická připojení nastavíme IdleConnectionTimeout a PortReuseMode na PrivatePortPool. Vlastnost IdleConnectionTimeout pomáhá řídit čas, po jehož uplynutí se nepoužívané připojení ukončí. Tím se sníží počet nepoužívaných připojení. Ve výchozím nastavení jsou nečinná připojení otevřená po neomezenou dobu. Sada hodnot musí být větší nebo rovna 10 minut. Doporučujeme hodnoty od 20 minut do 24 hodin. Vlastnost PortReuseMode 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í funkce Async/Await Vyhněte se blokovacím voláním: 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 a RequestTimeoutCancellationToken . Další podrobnosti najdete v našem průvodci odstraňováním potíží s vypršením časového limitu.
Logika pro opakování Další informace o tom, které chyby 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 automaticky opakuje v jiných oblastech. Podrobnosti o implementaci 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í do mezipaměti. Volání typu ReadDatabaseAsync nebo ReadDocumentCollectionAsync a CreateDatabaseQuery nebo CreateDocumentCollectionQuery budou mít za následek volání metadat služby, která spotřebovávají ze systémového limitu RU. CreateIfNotExist pro nastavení databáze by se také měla použít 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 Azure Cosmos DB SDK podporuje paralelní spouštění dotazů , aby se zlepšila latence a propustnost dotazů. Doporučujeme nastavit MaxConcurrency vlastnost v rámci parametru QueryRequestsOptions na počet oddílů, které máte. Pokud neznáte počet oddílů, začněte použitím int.MaxValuepříkazu , který vám poskytne nejlepší latenci. Pak tento počet snižte, dokud nebude vyhovovat omezením prostředků prostředí, abyste se vyhnuli 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ů.
Backoffs testování výkonu Při testování aplikace byste měli v intervalech implementovat zásady RetryAfter . Pokud respektujete omezení, pomůže vám to zajistit, abyste mezi opakovanými pokusy strávili minimální dobu čekáním.
Indexování Zásady indexování služby Azure Cosmos DB také umožňují určit, které cesty k dokumentům se mají zahrnout nebo vyloučit z indexování pomocí cest indexování (IndexingPolicy.IncludedPaths a IndexingPolicy.ExcludedPaths). Ujistěte se, že jste z indexování vyloučili nepoužívané cesty, aby se zápis zrychlil. Další informace o vytváření indexů pomocí sady SDK najdete v tématu Tipy k výkonu sady .NET SDK v3.
Velikost dokumentu Poplatky za zadanou operaci odpovídají přímo velikosti 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 úkolů Vzhledem k tomu, že volání služby Azure Cosmos DB se provádějí přes síť, možná budete muset měnit míru souběžnosti vašich požadavků, aby klientská aplikace strávila čekáním mezi požadavky co nejméně času. Pokud například používáte paralelní knihovnu úloh .NET, vytvořte v pořadí stovky úloh, které čtou nebo zapisují do služby Azure Cosmos DB.
Povolení metrik dotazů Pokud chcete více protokolovat spouště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řešené scénáře, jako jsou výjimky nebo kdy požadavky překročí očekávanou latenci.
DefaultTraceListener DefaultTraceListener představuje problémy s výkonem v produkčních prostředích, což způsobuje vysoké zatížení procesoru a vstupně-výstupních operací. Ujistěte se, že používáte nejnovější verze sady SDK, nebo odeberte defaultTraceListener z aplikace.
Nepoužívejte v identifikátorech žádné speciální znaky. Některé znaky jsou omezené a nelze je použít v některých identifikátorech: /, \, ?, #. Obecně se doporučuje 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 se zabránilo 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 s každou verzí mění, 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í. Neanalyzujte řetězec, abyste se vyhnuli změnám způsobujícím chybu. 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 provádí HttpClient požadavky HTTP bez ohledu na nakonfigurovaný režim připojení. V přímém režimu se protokol HTTP používá pro operace s metadaty a v režimu brány se používá pro operace roviny dat i metadat. Jednou ze základních funkcí HttpClient je zajistit, aby HttpClient služba reagovala na změny DNS ve vašem účtu přizpůsobením doby života připojení ve fondu. Dokud jsou připojení ve fondu otevřená, nereagují na změny DNS. Toto nastavení vynutí pravidelné zavření připojení ve fondu, aby vaše aplikace reagovala na změny DNS. Naším doporučením je přizpůsobit tuto hodnotu podle vašeho režimu připojení a zatížení, aby se vyvážil dopad častého vytváření nových připojení na výkon a nutnost reagovat na změny DNS (dostupnost). Hodnota 5 minut by byla dobrým začátkem, kterou je možné zvýšit, pokud ovlivňuje výkon, zejména v režimu brány.

Vlastní HttpClient můžete vložit prostřednictvím CosmosClientOptions.HttpClientFactory, například:

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

Zvýšení System.Net MaxConnections na hostitele při použití režimu brány Při použití režimu brány se požadavky Azure Cosmos DB provádějí přes HTTPS nebo REST. Vztahují se na ně výchozí limit 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 změnit hodnotu, můžete nastavit CosmosClientOptions.GatewayModeMaxConnectionLimit vyšší hodnotu.

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

U úloh, které mají datové části náročné na EnableContentResponseOnWrite vytváření, nastavte možnost žádosti na false. Služba už nevrátí vytvořený nebo aktualizovaný prostředek do sady SDK. Protože aplikace má objekt, který se vytváří, obvykle nepotřebuje, aby ho služba vrátila. Hodnoty v hlavičce jsou stále přístupné, například poplatky za požadavek. Zakázání odpovědi na obsah může pomoct zvýšit výkon, protože sada SDK už nemusí přidělovat paměť ani serializovat tělo odpovědi. Snižuje také využití šířky pásma sítě, což ještě více pomáhá výkonu.

Důležité

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

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

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

Pokud je ale každý tenant reprezentovaný jiným účtem služby Azure Cosmos DB, je nutné vytvořit samostatnou instanci klienta pro každý účet. Jednotný vzor stále platí pro každého klienta (jeden klient pro každý účet po celou dobu životnosti aplikace), ale pokud je počet tenantů vysoký, může být správa počtu klientů obtížná. Připojení se můžou zvýšit nad rámec limitů výpočetního prostředí a způsobovat 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í klientů (a tedy i počet tenantů), které může jedna výpočetní instance zpracovat. 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 tenanta mezi instancemi. Pokud každá výpočetní instance dokáže úspěšně zpracovat určitý omezený počet 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ů.
  • V případě zhuštěných úloh zvažte použití nejméně často používané mezipaměti jako struktury pro uložení instancí klientů a odstranění klientů pro tenanty, ke kterým se během časového intervalu nepodařilo získat přístup. Jednou z možností v .NET je MemoryCacheEntryOptions, kde lze použít RegisterPostEvictionCallback k odstranění neaktivních klientů a setSlidingExpiration lze použít k definování maximální doby pro 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í přímého režimu zvažte úpravy cosmosClientOptions.IdleTcpConnectionTimeout a CosmosClientOptions.PortReuseMode v konfiguraci přímého režimu tak, aby se ukončovala nepoužívané připojení a aby byl objem připojení pod kontrolou.

Další kroky

Ukázkovou aplikaci, která se používá k vyhodnocení vysoce výkonných scénářů ve službě Azure Cosmos DB 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 pro migraci do služby Azure Cosmos DB? Informace o existujícím databázovém clusteru můžete použít k plánování kapacity.