Dela via

Azure Cosmos DB SDK-observerbarhet

  • Artikel

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.

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"​
        }​
    }
}

Konfigurera OpenTelemetry

I det här avsnittet beskrivs den konfiguration som krävs för Azure Cosmos DB Java SDK och .NET SDK:er.

Om du vill använda OpenTelemetry med Azure Cosmos DB .NET SDK lägger du till källan i Azure.Cosmos.Operation 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 Portal för att förstå begärandeflödet i ditt program. Här är ett exempel på spårningsdata från en fråga mellan partitioner i transaktionssökningen i det vänstra navigeringsfältet i Azure Portal.

Skärmbild av distribuerad spårning av en Azure Cosmos DB-fråga mellan partitioner i Application Insights-transaktionssökningen.

Nästa steg