Azure Cosmos DB SDK-observerbarhet

Artikel
03/05/2024

GÄLLER FÖR: NoSQL

Azure Cosmos DB .NET och Java SDK:er stöder distribuerad spårning som hjälper dig att övervaka dina program. Att spåra flödet av begäranden är användbart vid felsökning, analys av svarstid och prestanda samt insamling av diagnostik. Instrumentspårning för dina program med OpenTelemetry, som är leverantörsneutral och har en uppsättning semantiska konventioner för att säkerställa ett standardiserat dataformat oavsett vilken exportör du väljer, eller använda Application Insights SDK eller Azure Monitor OpenTelemetry Distro.

Kom igång

Distribuerad spårning är tillgänglig i följande SDK:er:

SDK	Version som stöds	Kommentar
.NET v3 SDK	>= `3.36.0`	Den här funktionen är tillgänglig i både förhandsversioner och icke-förhandsversioner. För icke-förhandsversioner är det inaktiverat som standard. Du kan aktivera spårning genom att ange `DisableDistributedTracing = false` i `CosmosClientOptions.CosmosClientTelemetryOptions`.
Förhandsversion av .NET v3 SDK	>= `3.33.0-preview`	Den här funktionen är tillgänglig i både förhandsversioner och icke-förhandsversioner. För förhandsversioner är den aktiverad som standard. Du kan inaktivera spårning genom att ange `DisableDistributedTracing = true` i `CosmosClientOptions.CosmosClientTelemetryOptions`.
Java v4 SDK	>= `4.43.0`

Spårningsattribut

Azure Cosmos DB-spårningar följer OpenTelemetry-databasspecifikationen och tillhandahåller även flera anpassade attribut. Du kan se olika attribut beroende på hur din begäran fungerar, och dessa attribut är grundläggande attribut för alla begäranden.

Attribut	Typ	Description
`net.peer.name`	sträng	Azure Cosmos DB-värdnamn.
`db.name`	sträng	Azure Cosmos DB-databasnamn.
`db.system`	sträng	Identifierare för databastjänsten. Gäller `cosmosdb` för alla begäranden.
`db.operation`	sträng	Åtgärdsnamn, till exempel `CreateItemAsync`.
`db.cosmosdb.container`	sträng	Azure Cosmos DB-containernamn.
`db.cosmosdb.client_id`	sträng	Identifierare som representerar en unik klientinstans.
`db.cosmosdb.operation_type`	sträng	Åtgärdstyp, till exempel `Create`.
`db.cosmosdb.connection_mode`	sträng	Klientanslutningsläge. Antingen `direct` eller `gateway`.
`db.cosmosdb.status_code`	heltal	Statuskod för begäran.
`db.cosmosdb.sub_status_code`	heltal	Understatuskod för begäran.
`db.cosmosdb.request_charge`	dubbel	RU:er som förbrukas för åtgärden.
`db.cosmosdb.regions_contacted`	sträng	Lista över regioner som kontaktas i Azure Cosmos DB-kontot.
`user_agent.original`	sträng	Fullständig användaragentsträng som genereras av Azure Cosmos DB SDK.

Samla in diagnostik

Om du har konfigurerat loggar i spårningsprovidern kan du automatiskt hämta diagnostik för Azure Cosmos DB-begäranden som misslyckades eller hade hög svarstid. Dessa loggar kan hjälpa dig att diagnostisera misslyckade och långsamma begäranden utan att kräva någon anpassad kod för att samla in dem.

.NET
Java

Förutom att hämta diagnostikloggar för misslyckade begäranden kan du konfigurera olika tröskelvärden för svarstid för när diagnostik ska samlas in från lyckade begäranden. Standardvärdena är 100 ms för punktåtgärder och 500 ms för åtgärder som inte är punktåtgärder. Dessa tröskelvärden kan justeras via klientalternativ.

CosmosClientOptions options = new CosmosClientOptions()
{
    CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
    {
        DisableDistributedTracing = false,
        CosmosThresholdOptions = new CosmosThresholdOptions()
        {
            PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
            NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
        }
    },
};

Du kan konfigurera loggnivån för att styra vilka diagnostikloggar du får.

Loggningsnivå	beskrivning
Fel	Loggar endast för fel.
Varning	Loggar för fel och begäranden med hög svarstid baserat på konfigurerade tröskelvärden.
Information	Det finns inga specifika informationsnivåloggar. Loggar på den här nivån är desamma som med varning.

Beroende på din programmiljö finns det olika sätt att konfigurera loggnivån. Här är en exempelkonfiguration i appSettings.json:

{ 
    "Logging": {
        "LogLevel": {
            "Azure-Cosmos-Operation-Request-Diagnostics": "Information"
        }
    }
}

Förutom att hämta diagnostikloggar för misslyckade begäranden kan du konfigurera olika villkor för när diagnostik ska samlas in från lyckade begäranden. Villkoren omfattar ett svarstidströskelvärde för både punktåtgärder och icke-punktsåtgärder och ett tröskelvärde för begäranden som överskrider ett antal RU:er. Dessa tröskelvärden kan anges i Azure Cosmos DB-klienten.

    CosmosAsyncClient client = new CosmosClientBuilder()
            .endpoint("<Your account endpoint>")
            .key("<Your account key>")
            .clientTelemetryConfig(new CosmosClientTelemetryConfig()
                .diagnosticsThresholds(
                    new CosmosDiagnosticsThresholds()
                        .setPointOperationLatencyThreshold(Duration.ofMillis(100))
                        .setNonPointOperationLatencyThreshold(Duration.ofMillis(2000))
                        .setRequestChargeThreshold(100)))
            .buildAsyncClient();

Konfigurera OpenTelemetry

Om du vill använda OpenTelemetry med Azure Cosmos DB SDK:er lägger du till Azure.Cosmos.Operation källan i spårningsprovidern. OpenTelemetry är kompatibelt med många exportörer som kan mata in dina data. Följande exempel använder Azure Monitor OpenTelemetry Exporter, men du kan välja att konfigurera valfri exportör som du vill. Beroende på vilken exportör du väljer kan det uppstå en fördröjning vid inmatning av data på upp till några minuter.

Dricks

Om du använder Azure.Monitor.OpenTelemetry.Exporter paketet kontrollerar du att du använder version >= 1.0.0-beta.11. Om du använder ASP.NET Core och Azure Monitor rekommenderar vi att du använder Azure Monitor OpenTelemetry Distro i stället.

Det här exemplet visar hur du konfigurerar OpenTelemetry för en .NET-konsolapp. Se det fullständiga exemplet på GitHub.

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

Konfigurera Application Insights SDK

Det finns många olika sätt att konfigurera Application Insights beroende på vilket språk programmet är skrivet i och din beräkningsmiljö. Mer information finns i Application Insights-dokumentationen. Det kan ta upp till några minuter att mata in data i Application Insights.

Kommentar

Använd version >= 2.22.0-beta2 av Application Insights-paketet för din .NET-målmiljö.

Följande exempel visar hur du konfigurerar Application Insights för en .NET-konsolapp. Se det fullständiga exemplet på GitHub.

IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);

IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();

När spårningsdata matas in i Application Insights kan du visualisera dem i Azure-portalen för att förstå begärandeflödet i ditt program. Här är ett exempel på spårningsdata från en korspartitionsfråga i transaktionssökningen i det vänstra navigeringsfältet i Azure-portalen.

Share via