Sdílet prostřednictvím

Pozorovatelnost sady SDK služby Azure Cosmos DB

PLATÍ PRO: NoSQL

Sady SDK .NET a Java služby Azure Cosmos DB podporují distribuované trasování, které pomáhá 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 Poznámky
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 DisableDistributedTracing = false v CosmosClientOptions.CosmosClientTelemetryOptions.
.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 DisableDistributedTracing = truesouboru CosmosClientOptions.CosmosClientTelemetryOptions .
Java v4 SDK >= 4.43.0

Trasovací atributy

Trasování služby Azure Cosmos DB se řídí specifikací databáze OpenTelemetry a zároveň poskytuje 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.

Vlastnost Typ Popis
net.peer.name řetězec Název hostitele služby Azure Cosmos DB
db.name řetězec Název databáze Azure Cosmos DB
db.system řetězec Identifikátor databázové služby. Je cosmosdb určená pro všechny žádosti.
db.operation řetězec Název operace, např. CreateItemAsync.
db.cosmosdb.container řetězec Název kontejneru Azure Cosmos DB
db.cosmosdb.client_id řetězec Identifikátor představující jedinečnou instanci klienta
db.cosmosdb.operation_type řetězec Typ operace, např. Create.
db.cosmosdb.connection_mode řetězec 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 dvojitý Jednotky RU spotřebované během operace.
db.cosmosdb.regions_contacted řetězec Seznam oblastí kontaktovaných v účtu služby Azure Cosmos DB
user_agent.original řetězec Ú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 diagnostikovat neúspěšné a pomalé požadavky, aniž by bylo potřeba psát vlastní kód pro jejich zachycení.

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 1 sekundy pro operace bodu a 3 sekundy 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ň záznamu Popis
Chyba Protokoluje pouze chyby.
Upozorňující Záznamy chyb a požadavků s vysokou latencí podle nakonfigurovaných prahových hodnot.
Informace 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 zdroj Azure.Cosmos.Operation ke svému 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 může dojít ke zpoždění ingestování dat až několik minut.

Tip

Pokud používáte balíček 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.

Snímek obrazovky s distribuovaným trasováním dotazu azure Cosmos DB napříč oddíly ve vyhledávání transakcí Application Insights

Další kroky

  • Last updated on