Beobachtbarkeit des Azure Cosmos DB SDK

Gilt für:: ✅ NoSQL

Die Azure Cosmos DB .NET und Java SDKs unterstützen die verteilte Ablaufverfolgung, um Ihre Anwendungen zu überwachen. Die Ablaufverfolgung des Anforderungsflusses ist hilfreich beim Debuggen, analysieren von Latenz und Leistung sowie beim Erfassen von Diagnosen. Instrumentablaufverfolgung für Ihre Anwendungen mithilfe von OpenTelemetry, die anbieterneutral ist und über eine Reihe von semantischen Konventionen verfügt, um ein standardisiertes Datenformat unabhängig von Ihrem ausgewählten Exporter sicherzustellen oder das Application Insights SDK oder Azure Monitor OpenTelemetry Distro zu verwenden.

Get started

Verteiltes Tracing ist in den folgenden Software Development Kits (SDKs) verfügbar:

SDK	Unterstützte Version	Hinweise
.NET v3 SDK	>= `3.36.0`	Dieses Feature ist sowohl in der Vorschau als auch in Nichtvorschauversionen verfügbar. Bei Nichtvorschauversionen ist sie standardmäßig deaktiviert. Sie können die Ablaufverfolgung aktivieren, indem Sie `DisableDistributedTracing = false` in `CosmosClientOptions.CosmosClientTelemetryOptions` festlegen.
.NET v3 SDK Vorschau	>= `3.33.0-preview`	Dieses Feature ist sowohl in der Vorschau als auch in Nichtvorschauversionen verfügbar. Für Vorschauversionen ist sie standardmäßig aktiviert. Sie können die Ablaufverfolgung deaktivieren, indem Sie `DisableDistributedTracing = true` in `CosmosClientOptions.CosmosClientTelemetryOptions` festlegen.
Java v4 SDK	>= `4.43.0`

Ablaufverfolgungsattribute

Azure Cosmos DB-Ablaufverfolgungen folgen der OpenTelemetry-Datenbankspezifikation und stellen auch mehrere benutzerdefinierte Attribute bereit. Je nach Vorgang Ihrer Anforderung werden unterschiedliche Attribute angezeigt, und diese Attribute sind Kernattribute für alle Anforderungen.

Merkmal	Typ	Description
`net.peer.name`	Schnur	Azure Cosmos DB-Hostname.
`db.name`	Schnur	Azure Cosmos DB-Datenbankname.
`db.system`	Schnur	Bezeichner für den Datenbankdienst. Dient als `cosmosdb` für alle Anforderungen.
`db.operation`	Schnur	Vorgangsname, z. B. `CreateItemAsync`.
`db.cosmosdb.container`	Schnur	Azure Cosmos DB-Containername.
`db.cosmosdb.client_id`	Schnur	Bezeichner, der eine eindeutige Clientinstanz darstellt.
`db.cosmosdb.operation_type`	Schnur	Vorgangstyp, z. B. `Create`.
`db.cosmosdb.connection_mode`	Schnur	Clientverbindungsmodus. Entweder `direct` oder `gateway`.
`db.cosmosdb.status_code`	INT	Statuscode für die Anforderung.
`db.cosmosdb.sub_status_code`	INT	Unterstatuscode für die Anforderung.
`db.cosmosdb.request_charge`	double	Für den Vorgang verwendete RUs.
`db.cosmosdb.regions_contacted`	Schnur	Liste der Regionen, die im Azure Cosmos DB-Konto kontaktiert werden.
`user_agent.original`	Schnur	Vollständige Benutzer-Agent-Zeichenfolge, die vom Azure Cosmos DB SDK generiert wird.

Diagnose sammeln

Wenn Sie Protokolle in Ihrem Trace-Anbieter konfiguriert haben, können Sie automatisch Diagnosen für Azure Cosmos DB-Anforderungen abrufen, die fehlgeschlagen sind oder eine hohe Latenz aufwiesen. Mithilfe dieser Protokolle können Sie fehlerhafte und langsame Anforderungen diagnostizieren, ohne dass ein benutzerdefinierter Code zur Erfassung erforderlich ist.

.NET
Java

Zusätzlich zum Abrufen von Diagnoseprotokollen für fehlgeschlagene Anforderungen können Sie unterschiedliche Latenzschwellenwerte für den Zeitpunkt der Erfassung der Diagnose von erfolgreichen Anforderungen konfigurieren. Die Standardwerte sind 1 Sekunde für Punktvorgänge und 3 Sekunden für Vorgänge ohne Punkt. Diese Schwellenwerte können über Clientoptionen angepasst werden.

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

Sie können die Protokollebene konfigurieren, um zu steuern, welche Diagnoseprotokolle Sie erhalten.

Protokoll-Ebene	Description
Fehler	Protokolle nur für Fehler.
Warnung	Protokolle für Fehler und Anforderungen mit hoher Latenz basierend auf konfigurierten Schwellenwerten.
Informationen	Es gibt keine spezifischen Protokolle auf Informationsebene. Protokolle auf dieser Ebene sind identisch mit der Verwendung von Warning.

Je nach Anwendungsumgebung gibt es verschiedene Möglichkeiten zum Konfigurieren der Protokollebene. Hier sehen Sie eine Beispielkonfiguration in appSettings.json:

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

Zusätzlich zum Abrufen von Diagnoseprotokollen für fehlgeschlagene Anforderungen können Sie verschiedene Bedingungen konfigurieren, wann Diagnosen aus erfolgreichen Anforderungen erfasst werden sollen. Bedingungen umfassen einen Latenzschwellenwert sowohl für Punktvorgänge als auch für Nicht-Punkt-Vorgänge und einen Schwellenwert für Anforderungen, die eine Anzahl von RUs überschreiten. Diese Schwellenwerte können im Azure Cosmos DB-Client festgelegt werden.

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

Konfigurieren von OpenTelemetry

Um OpenTelemetry mit den Azure Cosmos DB SDKs zu verwenden, fügen Sie die Azure.Cosmos.Operation quelle zu Ihrem Tracing-Anbieter hinzu. OpenTelemetry ist mit vielen Exportern kompatibel, die Ihre Daten aufnehmen können. Im folgenden Beispiel wird der Azure Monitor OpenTelemetry Exporterverwendet, doch Sie können jeden beliebigen Exporter konfigurieren. Je nach ausgewähltem Exporter wird möglicherweise eine Verzögerung beim Aufnehmen von Daten von bis zu einigen Minuten angezeigt.

Tipp

Wenn Sie das Azure.Monitor.OpenTelemetry.Exporter Paket verwenden, stellen Sie sicher, dass Sie Version >= 1.0.0-beta.11verwenden. Wenn Sie ASP.NET Core und Azure Monitor verwenden, empfehlen wir stattdessen die Verwendung der Azure Monitor OpenTelemetry Distro .

In diesem Beispiel wird gezeigt, wie Sie OpenTelemetry für eine .NET-Konsolen-App konfigurieren. Sehen Sie sich das vollständige Beispiel auf GitHub an.

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

Konfigurieren des Application Insights SDK

Es gibt viele verschiedene Möglichkeiten zum Konfigurieren von Application Insights, abhängig von der Sprache, in der Ihre Anwendung geschrieben ist, und Ihrer Computeumgebung. Weitere Informationen finden Sie in der Application Insights-Dokumentation. Die Erfassung von Daten in Application Insights kann bis zu ein paar Minuten dauern.

Hinweis

Verwenden Sie version >= 2.22.0-beta2 des Application Insights-Pakets für Ihre .NET-Zielumgebung.

Das folgende Beispiel zeigt, wie Application Insights für eine .NET-Konsolen-App konfiguriert wird. Sehen Sie sich das vollständige Beispiel auf GitHub an.

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

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

Sobald Ablaufverfolgungsdaten in Application Insights aufgenommen wurden, können Sie sie im Azure-Portal visualisieren, um den Anforderungsfluss in Ihrer Anwendung zu verstehen. Hier sehen Sie ein Beispiel für Ablaufverfolgungsdaten aus einer partitionsübergreifenden Abfrage in der Transaktionssuche im linken Navigationsbereich des Azure-Portals.

Nächste Schritte

Feedback

War diese Seite hilfreich?

Last updated on 2025-12-24