Azure Cosmos DB SDK gözlemlenebilirliği

  • Makale

UYGULANANLAR: NoSQL

Azure Cosmos DB .NET ve Java SDK'ları, uygulamalarınızı izlemenize yardımcı olmak için dağıtılmış izlemeyi destekler. İstek akışının izlenilmesi hata ayıklama, gecikme süresi ve performansı analiz etme ve tanılama toplama konusunda yararlıdır. Satıcıdan bağımsız olan ve seçtiğiniz dışarı aktarmadan bağımsız olarak standartlaştırılmış bir veri biçimi sağlamak için bir dizi semantik kurala sahip olan OpenTelemetry kullanarak uygulamalarınız için izleme aracı izleme veya Application Analizler SDK veya Azure İzleyici OpenTelemetry Distro kullanın.

Kullanmaya başlayın

Dağıtılmış izleme aşağıdaki SDK'larda kullanılabilir:

SDK Desteklenen sürüm Notlar
.NET v3 SDK >= 3.36.0 Bu özellik hem önizleme hem de önizleme dışı sürümlerde kullanılabilir. Önizleme olmayan sürümler için varsayılan olarak kapalıdır. içinde CosmosClientOptions.CosmosClientTelemetryOptionsayarlayarak DisableDistributedTracing = false izlemeyi etkinleştirebilirsiniz.
.NET v3 SDK önizlemesi >= 3.33.0-preview Bu özellik hem önizleme hem de önizleme dışı sürümlerde kullanılabilir. Önizleme sürümleri için varsayılan olarak açıktır. içinde CosmosClientOptions.CosmosClientTelemetryOptionsayarlayarak DisableDistributedTracing = true izlemeyi devre dışı bırakabilirsiniz.
Java v4 SDK >= 4.43.0

öznitelikleri izleme

Azure Cosmos DB izlemeleri OpenTelemetry veritabanı belirtimini izler ve ayrıca çeşitli özel öznitelikler sağlar. İsteğinizin çalışmasına bağlı olarak farklı öznitelikler görebilirsiniz ve bu öznitelikler tüm isteklerin temel öznitelikleridir.

Öznitelik Type Veri Akışı Açıklaması
net.peer.name Dize Azure Cosmos DB ana bilgisayar adı.
db.name Dize Azure Cosmos DB veritabanı adı.
db.system Dize Veritabanı hizmetinin tanımlayıcısı. Tüm cosmosdb istekler içindir.
db.operation Dize İşlem adı, örn. CreateItemAsync.
db.cosmosdb.container Dize Azure Cosmos DB kapsayıcı adı.
db.cosmosdb.client_id Dize Benzersiz bir istemci örneğini temsil eden tanımlayıcı.
db.cosmosdb.operation_type Dize İşlem türü, örn. Create.
db.cosmosdb.connection_mode Dize İstemci bağlantı modu. direct veya gateway.
db.cosmosdb.status_code int İsteğin durum kodu.
db.cosmosdb.sub_status_code int İstek için alt durum kodu.
db.cosmosdb.request_charge çift İşlem için tüketilen RU'lar.
db.cosmosdb.regions_contacted Dize Azure Cosmos DB hesabında iletişim kurulan bölgelerin listesi.
user_agent.original Dize Azure Cosmos DB SDK'sı tarafından oluşturulan tam kullanıcı aracısı dizesi.

Tanılamaları toplama

İzleme sağlayıcınızda günlükleri yapılandırdıysanız, başarısız olan veya yüksek gecikme süresi olan Azure Cosmos DB isteklerine yönelik tanılamaları otomatik olarak alabilirsiniz. Bu günlükler, başarısız ve yavaş istekleri yakalamak için özel kod gerektirmeden tanılamanıza yardımcı olabilir.

Başarısız istekler için tanılama günlüklerini almaya ek olarak, başarılı isteklerden ne zaman tanılama toplayacağınız için farklı gecikme süresi eşikleri yapılandırabilirsiniz. Varsayılan değerler nokta işlemleri için 100 ms ve nokta dışı işlemler için 500 ms'tir. Bu eşikler istemci seçenekleri aracılığıyla ayarlanabilir.

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

Hangi tanılama günlüklerini aldığınızı denetlemek için günlük düzeyini yapılandırabilirsiniz.

Günlük Düzeyi Açıklama
Hata Yalnızca hataları günlüğe kaydeder.
Uyarı Yapılandırılan eşiklere göre hatalar ve yüksek gecikme süreli istekler için günlükler.
Bilgiler Belirli bilgi düzeyi günlükleri yok. Bu düzeydeki günlükler Uyarı'nın kullanılmasıyla aynıdır.

Uygulama ortamınıza bağlı olarak, günlük düzeyini yapılandırmanın farklı yolları vardır. aşağıda içinde örnek bir yapılandırma verilmişti appSettings.json:

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

OpenTelemetry'yi yapılandırma

OpenTelemetry'yi Azure Cosmos DB SDK'larıyla kullanmak için kaynağı izleme sağlayıcınıza ekleyin Azure.Cosmos.Operation . OpenTelemetry, verilerinizi alabilen birçok dışarı aktarıcıyla uyumludur. Aşağıdaki örnekte kullanır Azure Monitor OpenTelemetry Exporter, ancak istediğiniz herhangi bir dışarı vereni yapılandırmayı seçebilirsiniz. Seçtiğiniz dışarı aktarmaya bağlı olarak, verileri almada birkaç dakikaya kadar gecikme olduğunu görebilirsiniz.

İpucu

Paketini kullanıyorsanız Azure.Monitor.OpenTelemetry.Exporter , sürüm >= 1.0.0-beta.11kullandığınızdan emin olun. ASP.NET Core ve Azure İzleyici kullanıyorsanız bunun yerine Azure İzleyici OpenTelemetry Distro kullanmanızı öneririz.

Bu örnekte bir .NET konsol uygulaması için OpenTelemetry'nin nasıl yapılandırılır gösterilmektedir. GitHub'da tam örneğe bakın.

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

Uygulama Analizler SDK'sını yapılandırma

Uygulamanızın yazıldık diline ve işlem ortamınıza bağlı olarak Uygulama Analizler yapılandırmanın birçok farklı yolu vardır. Daha fazla bilgi için Uygulama Analizler belgelerine bakın. Verilerin Uygulama Analizler alınması birkaç dakika kadar sürebilir.

Not

Hedef .NET ortamınız için Application Analizler paketinin sürüm >= 2.22.0-beta2 değerini kullanın.

Aşağıdaki örnekte bir .NET konsol uygulaması için Uygulama Analizler'nin nasıl yapılandırılır gösterilmektedir. GitHub'da tam örneğe bakın.

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

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

İzleme verileri Application Analizler'a alındıktan sonra, uygulamanızdaki istek akışını anlamak için Azure portalında görselleştirebilirsiniz. Aşağıda, Azure portalının sol gezinti bölmesindeki işlem aramasında çapraz bölüm sorgusundan alınan izleme verilerinin bir örneği verilmiştir.

Screenshot of distributed tracing of an Azure Cosmos DB cross-partition query in the Application Insights transaction search.

Sonraki Adımlar