Azure Cosmos DB SDK-observerbarhet

  • 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.

Get started

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

SDK Version som stöds Notes
.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.

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

Samla in diagnostikdata

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 1 sekund för punktåtgärder och 3 sekunder 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å Description
Error 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 att använda 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

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.

Tips/Råd

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.

Anmärkning

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.

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

Nästa steg

  • Uppdaterades senast