Pozorovatelnost sady SDK služby Azure Cosmos DB
PLATÍ PRO: 
NoSQL
Sady .NET a sady Java SDK služby Azure Cosmos DB podporují distribuované trasování, které vám pomůže monitorovat vaše aplikace. Trasování toku požadavků je užitečné při ladění, analýze latence a výkonu a shromažďování diagnostiky. Trasování instrumentací pro vaše aplikace pomocí OpenTelemetry, která je neutrální dodavatelem a má sadu sémantických konvencí, které zajišťují standardizovaný formát dat bez ohledu na zvolený exportér, nebo použijte sadu Application Insights SDK nebo distro OpenTelemetry služby Azure Monitor.
Začínáme
Distribuované trasování je k dispozici v následujících sadách SDK:
| Sada SDK | Podporovaná verze | Notes |
|---|---|---|
| Sada .NET v3 SDK | >= 3.36.0 |
Tato funkce je k dispozici ve verzi Preview i ve verzích bez verze Preview. U verzí, které nejsou ve verzi Preview, je ve výchozím nastavení vypnuté. Trasování můžete povolit nastavením v CosmosClientOptions.CosmosClientTelemetryOptionssouboru DisableDistributedTracing = false . |
| .NET v3 SDK preview | >= 3.33.0-preview |
Tato funkce je k dispozici ve verzi Preview i ve verzích bez verze Preview. Pro verze Preview je ve výchozím nastavení zapnutá. Trasování můžete zakázat nastavením v CosmosClientOptions.CosmosClientTelemetryOptionssouboru DisableDistributedTracing = true . |
| Java v4 SDK | >= 4.43.0 |
Trasovací atributy
Trasování služby Azure Cosmos DB se řídí specifikací databáze OpenTelemetry a také poskytují několik vlastních atributů. V závislosti na operaci požadavku můžete zobrazit různé atributy a tyto atributy jsou základními atributy pro všechny požadavky.
| Atribut | Typ | Description |
|---|---|---|
net.peer.name |
string | Název hostitele služby Azure Cosmos DB |
db.name |
string | Název databáze Azure Cosmos DB |
db.system |
string | Identifikátor databázové služby. Je cosmosdb určená pro všechny žádosti. |
db.operation |
string | Název operace, např. CreateItemAsync. |
db.cosmosdb.container |
string | Název kontejneru Azure Cosmos DB |
db.cosmosdb.client_id |
string | Identifikátor představující jedinečnou instanci klienta |
db.cosmosdb.operation_type |
string | Typ operace, např. Create. |
db.cosmosdb.connection_mode |
string | Režim připojení klienta. Buďto direct nebo gateway. |
db.cosmosdb.status_code |
int | Stavový kód požadavku. |
db.cosmosdb.sub_status_code |
int | Dílčí stavový kód požadavku. |
db.cosmosdb.request_charge |
double | Jednotky RU spotřebované pro operaci. |
db.cosmosdb.regions_contacted |
string | Seznam oblastí kontaktovaných v účtu služby Azure Cosmos DB |
user_agent.original |
string | Úplný řetězec uživatelského agenta vygenerovaný sadou SDK služby Azure Cosmos DB |
Shromáždění diagnostiky
Pokud jste nakonfigurovali protokoly ve zprostředkovateli trasování, můžete automaticky získat diagnostiku pro požadavky Azure Cosmos DB, které selhaly nebo měly vysokou latenci. Tyto protokoly vám můžou pomoct s diagnostikou neúspěšných a pomalých požadavků, aniž byste museli zachytit vlastní kód.
Kromě získání diagnostických protokolů pro neúspěšné požadavky můžete nakonfigurovat různé prahové hodnoty latence, kdy shromažďovat diagnostiku z úspěšných požadavků. Výchozí hodnoty jsou 100 ms pro operace bodu a 500 ms pro operace bez bodu. Tyto prahové hodnoty je možné upravit prostřednictvím možností klienta.
CosmosClientOptions options = new CosmosClientOptions()
{
CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
{
DisableDistributedTracing = false,
CosmosThresholdOptions = new CosmosThresholdOptions()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
}
},
};
Úroveň protokolu můžete nakonfigurovat tak, aby kontrolujte, které diagnostické protokoly obdržíte.
| Úroveň protokolu | Popis |
|---|---|
| Chyba | Protokoluje pouze chyby. |
| Upozorňující | Protokoly pro chyby a požadavky s vysokou latencí na základě nakonfigurovaných prahových hodnot. |
| Informační | Neexistují žádné konkrétní protokoly na úrovni informací. Protokoly v této úrovni jsou stejné jako použití upozornění. |
V závislosti na prostředí aplikace existují různé způsoby konfigurace úrovně protokolu. Tady je ukázková konfigurace v appSettings.json:
{
"Logging": {
"LogLevel": {
"Azure-Cosmos-Operation-Request-Diagnostics": "Information"
}
}
}
Konfigurace OpenTelemetry
Pokud chcete použít OpenTelemetry se sadami SDK služby Azure Cosmos DB, přidejte Azure.Cosmos.Operation zdroj k poskytovateli trasování. OpenTelemetry je kompatibilní s mnoha vývozci, kteří mohou ingestovat vaše data. Následující ukázka používá metodu Azure Monitor OpenTelemetry Exporter, ale můžete se rozhodnout, že nakonfigurujete libovolného vývozce, kterého chcete. V závislosti na zvoleném vývozci se může zobrazit zpoždění ingestování dat až za několik minut.
Tip
Pokud balíček používáte Azure.Monitor.OpenTelemetry.Exporter , ujistěte se, že používáte verzi >= 1.0.0-beta.11.
Pokud používáte ASP.NET Core a Azure Monitor, doporučujeme místo toho použít distro OpenTelemetry pro Azure Monitor.
Tato ukázka ukazuje, jak nakonfigurovat OpenTelemetry pro konzolovou aplikaci .NET. Podívejte se na úplnou ukázku na GitHubu.
ResourceBuilder resource = ResourceBuilder.CreateDefault().AddService(
serviceName: serviceName,
serviceVersion: "1.0.0");
// Set up logging to forward logs to chosen exporter
using ILoggerFactory loggerFactory
= LoggerFactory.Create(builder => builder
.AddConfiguration(configuration.GetSection("Logging"))
.AddOpenTelemetry(options =>
{
options.IncludeFormattedMessage = true;
options.SetResourceBuilder(resource);
options.AddAzureMonitorLogExporter(o => o.ConnectionString = aiConnectionString); // Set up exporter of your choice
}));
/*.AddFilter(level => level == LogLevel.Error) // Filter is irrespective of event type or event name*/
AzureEventSourceLogForwarder logforwader = new AzureEventSourceLogForwarder(loggerFactory);
logforwader.Start();
// Configure OpenTelemetry trace provider
AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);
_traceProvider = Sdk.CreateTracerProviderBuilder()
.AddSource("Azure.Cosmos.Operation", // Cosmos DB source for operation level telemetry
"Sample.Application")
.AddAzureMonitorTraceExporter(o => o.ConnectionString = aiConnectionString) // Set up exporter of your choice
.AddHttpClientInstrumentation() // Added to capture HTTP telemetry
.SetResourceBuilder(resource)
.Build();
Konfigurace sady Application Insights SDK
Application Insights můžete nakonfigurovat mnoha různými způsoby v závislosti na jazyce, ve kterém je vaše aplikace napsaná a ve vašem výpočetním prostředí. Další informace najdete v dokumentaci k Application Insights. Příjem dat do Application Insights může trvat až několik minut.
Poznámka:
Použijte verzi >= 2.22.0-beta2 balíčku Application Insights pro cílové prostředí .NET.
Následující ukázka ukazuje, jak nakonfigurovat Application Insights pro konzolovou aplikaci .NET. Podívejte se na úplnou ukázku na GitHubu.
IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);
IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();
Jakmile se data trasování ingestují do Application Insights, můžete je vizualizovat na webu Azure Portal, abyste porozuměli toku požadavků ve vaší aplikaci. Tady je příklad trasovacích dat z dotazu napříč oddíly ve vyhledávání transakcí v levém navigačním panelu webu Azure Portal.
