Einblick in Azure Cosmos DB SDKs
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.
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"
}
}
}
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.
