Pengamatan Azure Cosmos DB SDK
BERLAKU UNTUK: 
NoSQL
Azure Cosmos DB .NET dan Java SDK mendukung pelacakan terdistribusi untuk membantu Anda memantau aplikasi Anda. Melacak alur permintaan sangat membantu dalam penelusuran kesalahan, menganalisis latensi dan performa, dan mengumpulkan diagnostik. Pelacakan instrumen untuk aplikasi Anda menggunakan OpenTelemetry, yang netral vendor dan memiliki serangkaian konvensi semantik untuk memastikan format data standar terlepas dari pengekspor yang Anda pilih, atau menggunakan Application Insights SDK atau Distro OpenTelemetry Azure Monitor.
Memulai
Pelacakan terdistribusi tersedia di SDK berikut:
| SDK | Versi yang didukung | Catatan |
|---|---|---|
| .NET v3 SDK | >= 3.36.0 |
Fitur ini tersedia dalam versi pratinjau dan non-pratinjau. Untuk versi non-pratinjau, versi non-pratinjau nonaktif secara default. Anda dapat mengaktifkan pelacakan dengan mengatur DisableDistributedTracing = false di CosmosClientOptions.CosmosClientTelemetryOptions. |
| Pratinjau .NET v3 SDK | >= 3.33.0-preview |
Fitur ini tersedia dalam versi pratinjau dan non-pratinjau. Untuk versi pratinjau, versi tersebut aktif secara default. Anda dapat menonaktifkan pelacakan dengan mengatur DisableDistributedTracing = true di CosmosClientOptions.CosmosClientTelemetryOptions. |
| Java v4 SDK | >= 4.43.0 |
Lacak atribut
Jejak Azure Cosmos DB mengikuti spesifikasi database OpenTelemetry dan juga menyediakan beberapa atribut kustom. Anda dapat melihat atribut yang berbeda tergantung pada pengoperasian permintaan Anda, dan atribut ini adalah atribut inti untuk semua permintaan.
| Atribut | Tipe | Deskripsi |
|---|---|---|
net.peer.name |
string | Nama host Azure Cosmos DB. |
db.name |
string | Nama database Azure Cosmos DB. |
db.system |
string | Pengidentifikasi untuk layanan database. Adalah cosmosdb untuk semua permintaan. |
db.operation |
string | Nama operasi, misalnya. CreateItemAsync. |
db.cosmosdb.container |
string | Nama kontainer Azure Cosmos DB. |
db.cosmosdb.client_id |
string | Pengidentifikasi yang mewakili instans klien unik. |
db.cosmosdb.operation_type |
string | Jenis operasi, misalnya. Create. |
db.cosmosdb.connection_mode |
string | Mode koneksi klien. Salah satu direct atau gateway. |
db.cosmosdb.status_code |
int | Kode status untuk permintaan. |
db.cosmosdb.sub_status_code |
int | Kode sub status untuk permintaan tersebut. |
db.cosmosdb.request_charge |
ganda | RU yang digunakan untuk operasi. |
db.cosmosdb.regions_contacted |
string | Daftar wilayah yang dihubungi di akun Azure Cosmos DB. |
user_agent.original |
string | String agen pengguna penuh yang dihasilkan oleh Azure Cosmos DB SDK. |
Mengumpulkan diagnostik
Jika Anda mengonfigurasi log di penyedia pelacakan, Anda bisa secara otomatis mendapatkan diagnostik untuk permintaan Azure Cosmos DB yang gagal atau memiliki latensi tinggi. Log ini dapat membantu Anda mendiagnosis permintaan yang gagal dan lambat tanpa memerlukan kode kustom apa pun untuk menangkapnya.
Selain mendapatkan log diagnostik untuk permintaan yang gagal, Anda dapat mengonfigurasi ambang latensi yang berbeda kapan harus mengumpulkan diagnostik dari permintaan yang berhasil. Nilai defaultnya adalah 100 ms untuk operasi titik dan 500 ms untuk operasi non titik. Ambang batas ini dapat disesuaikan melalui opsi klien.
CosmosClientOptions options = new CosmosClientOptions()
{
CosmosClientTelemetryOptions = new CosmosClientTelemetryOptions()
{
DisableDistributedTracing = false,
CosmosThresholdOptions = new CosmosThresholdOptions()
{
PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(100),
NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(500)
}
},
};
Anda dapat mengonfigurasi tingkat log untuk mengontrol log diagnostik mana yang Anda terima.
| Tingkat log | Deskripsi |
|---|---|
| Kesalahan | Log hanya untuk kesalahan. |
| Peringatan | Log untuk kesalahan dan permintaan latensi tinggi berdasarkan ambang batas yang dikonfigurasi. |
| Informasi | Tidak ada log tingkat informasi tertentu. Log dalam tingkat ini sama dengan menggunakan Peringatan. |
Bergantung pada lingkungan aplikasi Anda, ada berbagai cara untuk mengonfigurasi tingkat log. Berikut adalah konfigurasi sampel di appSettings.json:
{
"Logging": {
"LogLevel": {
"Azure-Cosmos-Operation-Request-Diagnostics": "Information"
}
}
}
Mengonfigurasi OpenTelemetry
Bagian ini menjelaskan konfigurasi yang diperlukan untuk Azure Cosmos DB Java SDK dan .NET SDK.
Untuk menggunakan OpenTelemetry dengan Azure Cosmos DB .NET SDK, tambahkan sumber ke Azure.Cosmos.Operation penyedia pelacakan Anda. OpenTelemetry kompatibel dengan banyak pengekspor yang dapat menyerap data Anda. Sampel berikut menggunakan Azure Monitor OpenTelemetry Exporter, tetapi Anda dapat memilih untuk mengonfigurasi pengekspor apa pun yang Anda inginkan. Bergantung pada pengekspor yang Anda pilih, Anda mungkin melihat penundaan menyerap data hingga beberapa menit.
Tip
Jika Anda menggunakan Azure.Monitor.OpenTelemetry.Exporter paket, pastikan Anda menggunakan versi >= 1.0.0-beta.11.
Jika Anda menggunakan ASP.NET Core dan Azure Monitor, sebaiknya gunakan Distro OpenTelemetry Azure Monitor sebagai gantinya.
Sampel ini menunjukkan cara mengonfigurasi OpenTelemetry untuk aplikasi konsol .NET. Lihat sampel lengkap di 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();
Mengonfigurasi Application Insights SDK
Ada banyak cara berbeda untuk mengonfigurasi Application Insights tergantung pada bahasa yang ditulis aplikasi Anda dan lingkungan komputasi Anda. Untuk informasi lebih lanjut, lihat Dokumentasi Application Insights. Penyerapan data ke Dalam Application Insights dapat memakan waktu hingga beberapa menit.
Catatan
Gunakan versi >= 2.22.0-beta2 paket Application Insights untuk lingkungan .NET target Anda.
Sampel berikut menunjukkan cara mengonfigurasi Application Insights untuk aplikasi konsol .NET. Lihat sampel lengkap di GitHub.
IServiceCollection services = new ServiceCollection();
services.AddApplicationInsightsTelemetryWorkerService((ApplicationInsightsServiceOptions options) => options.ConnectionString = aiConnectionString);
IServiceProvider serviceProvider = services.BuildServiceProvider();
telemetryClient = serviceProvider.GetRequiredService<TelemetryClient>();
Setelah data pelacakan diserap ke dalam Application Insights, Anda dapat memvisualisasikannya di portal Azure untuk memahami alur permintaan di aplikasi Anda. Berikut adalah contoh data pelacakan dari kueri lintas partisi dalam pencarian transaksi di navigasi kiri portal Azure.
