Einblick in Azure Cosmos DB SDKs

Artikel
03/08/2024

GILT FÜR: NoSQL

Die .NET und Java SDKs von Azure Cosmos DB unterstützen die verteilte Ablaufverfolgung zur Überwachung Ihrer Anwendungen. Das Nachverfolgen des Anforderungsflusses hilft beim Debuggen, Analysieren von Latenz und Leistung sowie beim Sammeln von Diagnosen. Instrumentieren Sie die Ablaufverfolgung für Ihre Anwendungen mithilfe von OpenTelemetry. Dies ist anbieterneutral und verfügt über eine Reihe semantischer Konventionen, um unabhängig vom ausgewählten Exporter ein standardisiertes Datenformat zu gewährleisten. Sie können aber auch das Application Insights SDK oder die Azure Monitor OpenTelemetry-Distribution verwenden.

Erste Schritte

Die verteilte Ablaufverfolgung ist in folgenden SDKs verfügbar:

SDK	Unterstützte Version	Hinweise
.NET v3 SDK	>= `3.36.0`	Dieses Feature ist sowohl in der Vorschau als auch in Nicht-Vorschauversionen verfügbar. Für Nicht-Vorschauversionen ist es 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 Nicht-Vorschauversionen verfügbar. Für Vorschauversionen ist es 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 entsprechen der OpenTelemetry-Datenbankspezifikation und bieten außerdem mehrere benutzerdefinierte Attribute. Je nach Vorgang Ihrer Anforderung können unterschiedliche Attribute angezeigt werden, und diese Attribute sind Kernattribute für alle Anforderungen.

attribute	type	Beschreibung
`net.peer.name`	Zeichenfolge	Azure Cosmos DB-Hostname.
`db.name`	Zeichenfolge	Azure Cosmos DB-Datenbankname.
`db.system`	Zeichenfolge	Bezeichner für den Datenbankdienst. Dient als `cosmosdb` für alle Anforderungen.
`db.operation`	Zeichenfolge	Vorgangsname, z. B. `CreateItemAsync`.
`db.cosmosdb.container`	Zeichenfolge	Azure Cosmos DB-Containername.
`db.cosmosdb.client_id`	Zeichenfolge	Bezeichner, der eine eindeutige Clientinstanz darstellt.
`db.cosmosdb.operation_type`	Zeichenfolge	Vorgangstyp, z. B. `Create`.
`db.cosmosdb.connection_mode`	Zeichenfolge	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`	Zeichenfolge	Liste der Regionen, die im Azure Cosmos DB-Konto kontaktiert werden.
`user_agent.original`	Zeichenfolge	Vollständige Benutzer-Agent-Zeichenfolge, die vom Azure Cosmos DB SDK generiert wird.

Sammeln von Diagnosen

Wenn Sie Protokolle in Ihrem Ablaufverfolgungsanbieter konfiguriert haben, können Sie automatisch Diagnosen für Azure Cosmos DB-Anforderungen abrufen, die einen Fehler 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 fehlerhafte Anforderungen können Sie verschiedene Latenzschwellenwerte für den Zeitpunkt konfigurieren, zu dem Diagnosen aus erfolgreichen Anforderungen gesammelt werden sollen. Die Standardwerte sind 100 ms für Punktvorgänge und 500 ms 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 festzulegen, welche Diagnoseprotokolle Sie erhalten.

Protokollebene	BESCHREIBUNG
Fehler	Nur Protokolle 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 dieser Ebene entsprechen der Verwendung von Warnungen.

Je nach Anwendungsumgebung gibt es verschiedene Möglichkeiten, die Protokollebene zu konfigurieren. Hier sehen Sie eine Beispielkonfiguration in appSettings.json:

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

Zusätzlich zum Abrufen von Diagnoseprotokollen für fehlerhafte Anforderungen können Sie verschiedene Bedingungen für den Zeitpunkt konfigurieren, zu dem Diagnosen aus erfolgreichen Anforderungen gesammelt werden sollen. Zu den Bedingungen gehören ein Latenzschwellenwert für Punktvorgänge und Vorgänge ohne Punkt sowie ein 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

Wenn Sie OpenTelemetry mit den Azure Cosmos DB SDKs verwenden möchten, fügen Sie Ihrem Ablaufverfolgungsanbieter die Quelle Azure.Cosmos.Operation hinzu. OpenTelemetry ist mit vielen Exportern kompatibel, die Ihre Daten erfassen können. Im folgenden Beispiel wird der Azure Monitor OpenTelemetry Exporterverwendet, doch Sie können jeden beliebigen Exporter konfigurieren. Je nach ausgewähltem Exporter kann es bei der Erfassung von Daten zu einer Verzögerung von einigen Minuten kommen.

Tipp

Wenn Sie das Paket Azure.Monitor.OpenTelemetry.Exporter verwenden, stellen Sie sicher, dass Sie mindestens Version 1.0.0-beta.11 verwenden. Wenn Sie ASP.NET Core und Azure Monitor verwenden, empfiehlt es sich, stattdessen die Azure Monitor OpenTelemetry-Distribution zu verwenden.

In diesem Beispiel wird gezeigt, wie Sie OpenTelemetry für eine .NET-Konsolen-App konfigurieren. Das vollständige Beispiel finden Sie auf 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();

Konfigurieren des Application Insights SDK

Es gibt viele verschiedene Möglichkeiten, Application Insights abhängig von der Sprache, in der Ihre Anwendung geschrieben wird, und Ihrer Compute-Umgebung zu konfigurieren. Weitere Informationen finden Sie in der Dokumentation zu Application Insights. Die Erfassung von Daten in Application Insights kann einige Minuten dauern.

Hinweis

Verwenden Sie mindestens 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. Das vollständige Beispiel finden Sie auf GitHub.

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

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

Sobald Ablaufverfolgungsdaten in Application Insights erfasst wurden, können Sie diese 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.