.NET, Node.js ve Python uygulamaları için Azure İzleyici OpenTelemetry Exporter'ı etkinleştirme (önizleme)

Bu makalede OpenTelemetry tabanlı Azure İzleyici Önizleme teklifinin nasıl etkinleştirileceği ve yapılandırıldığı açıklanır. Bu makaledeki yönergeleri tamamladıktan sonra, OpenTelemetry izlemelerini Azure İzleyici Uygulaması Analizler gönderebileceksiniz. OpenTelemetry hakkında daha fazla bilgi edinmek için bkz. OpenTelemetry'ye genel bakış veya OpenTelemetry SSS.

Önemli

.NET, Node.js ve Python uygulamaları için Azure İzleyici OpenTelemetry Exporter şu anda önizleme aşamasındadır. Beta veya önizleme aşamasında olan ya da başka bir şekilde henüz genel kullanıma sunulmamış olan Azure özelliklerinde geçerli olan yasal koşullar için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

Önizleme sürümünün sınırlamaları

Bu önizlemenin sizin için uygun olup olmadığını dikkatle göz önünde bulundurun. Yalnızca dağıtılmış izlemeyi etkinleştirir ve şunları dışlar:

Tam özellik deneyimine ihtiyacınız varsa OpenTelemetry tabanlı teklif olgunlaşıncaya kadar mevcut Application Analizler ASP.NET veya ASP.NET Core SDK'sını kullanın.

Başlarken

Uygulamanızı OpenTelemetry ile izlemek için bu bölümdeki adımları izleyin.

Önkoşullar

  • En az .NET Framework 4.6.1 olan resmi olarak desteklenen bir .NET Core veya .NET Framework sürümünü kullanan uygulama

İstemci kitaplıklarını yükleme

En son Azure.Monitor.OpenTelemetry.Exporter NuGet paketini yükleyin:

dotnet add package --prerelease Azure.Monitor.OpenTelemetry.Exporter 

"Azure.Monitor.OpenTelemetry.Exporter paketi için kullanılabilir sürüm yok" gibi bir hata alırsanız, bunun nedeni büyük olasılıkla NuGet paket kaynaklarının ayarının eksik olmasıdır. Şu seçenekle kaynağı belirtmeyi -s deneyin:

# Install the latest package with the NuGet package source specified.
dotnet add package --prerelease Azure.Monitor.OpenTelemetry.Exporter -s https://api.nuget.org/v3/index.json

Azure İzleyici Uygulama Analizler etkinleştirme

Bu bölümde OpenTelemetry'nin nasıl etkinleştirileceğine dair yönergeler sağlanır.

OpenTelemetry izleme kodu ekleme

Aşağıdaki kod, OpenTelemetry TracerProvider'ı ayarlayarak bir C# konsol uygulamasında OpenTelemetry'yi etkinleştirmeyi gösterir. Bu kod, uygulama başlangıcında olmalıdır. ASP.NET Core için genellikle uygulama Startup sınıfının yönteminde ConfigureServices yapılır. ASP.NET uygulamalar için genellikle içinde Global.asax.csyapılır.

using System.Diagnostics;
using Azure.Monitor.OpenTelemetry.Exporter;
using OpenTelemetry;
using OpenTelemetry.Trace;

public class Program
{
    private static readonly ActivitySource MyActivitySource = new ActivitySource(
        "OTel.AzureMonitor.Demo");

    public static void Main()
    {
        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSource("OTel.AzureMonitor.Demo")
            .AddAzureMonitorTraceExporter(o =>
            {
                o.ConnectionString = "<Your Connection String>";
            })
            .Build();

        using (var activity = MyActivitySource.StartActivity("TestActivity"))
        {
            activity?.SetTag("CustomTag1", "Value1");
            activity?.SetTag("CustomTag2", "Value2");
        }

        System.Console.WriteLine("Press Enter key to exit.");
        System.Console.ReadLine();
    }
}

Not

Activity Ad alanından ve ActivitySource sınıfları System.Diagnostics sırasıyla ve Tracer'nin Span OpenTelemetry kavramlarını temsil ediyor. kullanarak yerine TracerProvideroluşturucusunu kullanarak doğrudan oluşturursunuzActivitySource. Her ActivitySource sınıf kullanılarak AddSource()açıkça bağlanmalıdırTracerProvider. Bunun nedeni OpenTelemetry izleme API'sinin bölümlerinin doğrudan .NET çalışma zamanına dahil edilmiş olmasıdır. Daha fazla bilgi edinmek için bkz. OpenTelemetry .NET İzleme API'sine Giriş.

İpucu

Popüler çerçeveler ve kitaplıklar arasında telemetri verilerini otomatik olarak toplamaya yönelik izleme kitaplıkları ekleyin.

Uygulama Analizler bağlantı dizesini ayarlama

Önceki koddaki yer tutucuyu <Your Connection String> Application Analizler kaynağınızdaki bağlantı dizesiyle değiştirin.

Screenshot of the Application Insights connection string.

Verilerin aktığını onaylayın

Uygulamanızı çalıştırın ve Azure portal Uygulama Analizler Kaynağı sekmesini açın. Verilerin portalda görünmesi birkaç dakika sürebilir.

Not

Uygulamayı çalıştıramıyorsanız veya beklendiği gibi veri almıyorsanız bkz . Sorun giderme.

Screenshot of the Application Insights Overview tab with server requests and server response time highlighted.

Önemli

Aynı Uygulama Analizler kaynağına telemetri yayan iki veya daha fazla hizmetiniz varsa, bunları Uygulama Haritası'nda düzgün bir şekilde göstermek için Bulut Rolü Adları'nı ayarlamanız gerekir.

Application Analizler izlemesini kullanmanın bir parçası olarak tanılama verilerini toplar ve Microsoft'a göndeririz. Bu veriler, Uygulama Analizler çalıştırmamıza ve geliştirmemize yardımcı olur. Gereksiz veri toplamayı devre dışı bırakma seçeneğiniz vardır. Daha fazla bilgi edinmek için bkz. Azure Uygulaması Analizler'da statsbeat.

Bulut Rolü Adını ve Bulut Rolü Örneğini Ayarlama

Kaynak öznitelikleri aracılığıyla Bulut Rolü Adı'nı ve Bulut Rolü Örneğini ayarlayabilirsiniz. Bu adım, Bulut Rolü Adı ve Bulut Rolü Örneğini varsayılan değerlerinden ekibiniz için anlamlı bir değere güncelleştirir. Bunlar Uygulama Haritası'nda bir düğümün altında ad olarak görünür. Bulut Rolü Adı, ve özniteliklerini kullanır service.namespaceservice.name, ancak ayarlı değilse service.namespace değerine geri dönerservice.name. Bulut Rolü Örneği öznitelik değerini kullanır service.instance.id .

// Setting role name and role instance
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};
var resourceBuilder = ResourceBuilder.CreateDefault().AddAttributes(resourceAttributes);
// Done setting role name and role instance

// Set ResourceBuilder on the provider.
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .SetResourceBuilder(resourceBuilder)
        .AddSource("OTel.AzureMonitor.Demo")
        .AddAzureMonitorTraceExporter(o =>
        {
            o.ConnectionString = "<Your Connection String>";
        })
        .Build();

Kaynakların standart öznitelikleri hakkında bilgi için bkz. Kaynak Anlam Kuralları.

Örnekleme

Örnekleme OpenTelemetry'de desteklenir, ancak şu anda Azure İzleyici OpenTelemetry Exporter'da desteklenmez.

Uyarı

OpenTelemetry'de örneklemenin etkinleştirilmesi standart ve günlük tabanlı ölçümleri son derece yanlış hale getirir ve bu da tüm Uygulama Analizler deneyimlerini olumsuz etkiler. Ayrıca, mevcut Uygulama Analizler SDK'ları ile birlikte örneklemenin etkinleştirilmesi, bozuk izlemelere neden olur.

İzleme kitaplıkları

Aşağıdaki kitaplıklar önizleme sürümüyle çalışacak şekilde doğrulanmıştır.

Uyarı

İzleme kitaplıkları deneysel OpenTelemetry belirtimlerini temel alır. Microsoft'un önizleme desteği taahhüdü, aşağıdaki kitaplıkların Verileri Azure İzleyici Uygulaması Analizler yaymasını sağlamaktır, ancak hataya neden olan değişikliklerin veya deneysel eşlemenin bazı veri öğelerini engellemesi mümkündür.

HTTP

Veritabanı

Not

Önizleme teklifi yalnızca HTTP ve veritabanı isteklerini işleyen izlemeleri içerir. Daha fazla bilgi edinmek için bkz. OpenTelemetry Semantic Conventions.

Telemetriyi değiştirme

Bu bölümde telemetrinin nasıl değiştirileceği açıklanmaktadır.

Span öznitelikleri ekleme

Span öznitelikleri eklemek için aşağıdaki iki yoldan birini kullanın:

Bu öznitelikler telemetrinize özel özellik eklemeyi içerebilir. Uygulama Analizler şemasında İstemci IP'leri gibi isteğe bağlı alanlar ayarlamak için öznitelikleri de kullanabilirsiniz.

İpucu

İzleme kitaplıkları tarafından sağlanan seçenekleri kullanmanın avantajı, kullanılabilir olduğunda bağlamın tamamının kullanılabilir olmasıdır. Sonuç olarak, kullanıcılar daha fazla öznitelik eklemeyi veya filtrelemeyi seçebilir. Örneğin, HttpClient izleme kitaplığındaki zenginleştirme seçeneği, kullanıcılara httpRequestMessage'ın kendisine erişim verir. Öğeden herhangi bir şey seçebilir ve bir öznitelik olarak depolayabilirler.

Özel özellik ekleme

Spans'a eklediğiniz tüm öznitelikler özel özellikler olarak dışarı aktarılır. İsteklerdeki customDimensions alanını veya Application Analizler'daki bağımlılıklar tablolarını doldurur.

  1. Birçok izleme kitaplığı zenginleştirme seçeneği sunar. Yönergeler için tek tek izleme kitaplıklarının benioku dosyalarına bakın:

  2. Özel işlemci kullanın:

İpucu

Burada gösterilen işlemciyi Azure İzleyici Dışarı Vereni'nin önüne ekleyin.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
        .AddSource("OTel.AzureMonitor.Demo")
        .AddProcessor(new ActivityEnrichingProcessor())
        .AddAzureMonitorTraceExporter(o =>
        {
                o.ConnectionString = "<Your Connection String>"
        })
        .Build();

Aşağıdaki kodla projenize ekleyin ActivityEnrichingProcessor.cs :

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Trace;

public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

Kullanıcı IP'sini ayarlama

özniteliğini span üzerinde ayarlayarak http.client_ip istekler için client_IP alanını doldurabilirsiniz. Uygulama Analizler kullanıcı konumu özniteliklerini oluşturmak için IP adresini kullanır ve varsayılan olarak atar.

Özel özellik ekleme örneğini kullanın, ancak içindeki ActivityEnrichingProcessor.csaşağıdaki kod satırlarını değiştirin:

// only applicable in case of activity.Kind == Server
activity.SetTag("http.client_ip", "<IP Address>");

Telemetri filtreleme

Telemetriyi uygulamanızdan çıkmadan önce filtrelemek için aşağıdaki yöntemleri kullanabilirsiniz.

  1. Birçok izleme kitaplığı bir filtre seçeneği sağlar. Yönergeler için tek tek izleme kitaplıklarının benioku dosyalarına bakın:

  2. Özel işlemci kullanın:

    using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSource("OTel.AzureMonitor.Demo")
            .AddProcessor(new ActivityFilteringProcessor())
            .AddAzureMonitorTraceExporter(o =>
            {
                    o.ConnectionString = "<Your Connection String>"
            })
            .Build();
    

    Aşağıdaki kodla projenize ekleyin ActivityFilteringProcessor.cs :

    using System.Diagnostics;
    using OpenTelemetry;
    using OpenTelemetry.Trace;
    
    public class ActivityFilteringProcessor : BaseProcessor<Activity>
    {
        public override void OnStart(Activity activity)
        {
            // prevents all exporters from exporting internal activities
            if (activity.Kind == ActivityKind.Internal)
            {
                activity.IsAllDataRequested = false;
            }
        }
    }
    
  3. Belirli bir kaynak kullanılarak AddSource("ActivitySourceName")açıkça eklenmezse, bu kaynak kullanılarak oluşturulan etkinliklerin hiçbiri dışarı aktarılamaz.

OTLP DışarıYırıcısını Etkinleştirme

Telemetrinizi iki konuma göndermek için Azure İzleyici Exporter ile birlikte OpenTelemetry Protocol (OTLP) Exporter'ı etkinleştirmek isteyebilirsiniz.

Not

OTLP İhracatçısı yalnızca kolaylık sağlamak için gösterilir. OTLP İhracatçısı'nı veya herhangi bir bileşeni ya da üçüncü taraf deneyimleri aşağı akışını resmi olarak desteklemiyoruz. Azure desteği sınırı dışındaki OpenTelemetry için OpenTelemetry-Collector sorunlarıyla ilgili bir sorun açmanızı öneririz.

  1. OpenTelemetry.Exporter.OpenTelemetryProtocol paketini ve Azure.Monitor.OpenTelemetry.Exporter'ı projenize yükleyin.

  2. Aşağıdaki kod parçacığını ekleyin. Bu örnekte, OTLP alıcısı çalışan bir OpenTelemetry Toplayıcınız olduğu varsayılır. Ayrıntılar için GitHub örneğine bakın.

    // Sends data to Application Insights as well as OTLP
    using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSource("OTel.AzureMonitor.Demo")
            .AddAzureMonitorTraceExporter(o =>
            {
                o.ConnectionString = "<Your Connection String>"
            })
            .AddOtlpExporter()
            .Build();
    

Sorun giderme

Bu bölümde sorun giderme konusunda yardım sağlanır.

Tanılama günlüğünü etkinleştirme

Azure İzleyici DışarıYılıcısı kendi iç günlüğü için EventSource kullanır. Dışarı aktarıcı günlükleri, OpenTelemetry-AzureMonitor-Exporter adlı kaynağı kabul ederek herhangi bir EventListener tarafından kullanılabilir. Sorun giderme adımları için bkz. OpenTelemetry Sorun Giderme.

Bilinen sorunlar

Azure İzleyici OpenTelemetry Exporters ile ilgili bilinen sorunlar şunlardır:

  • Bağımlılık telemetrisinde işlem adı eksik, bu da hataları ve performans sekmesi deneyimini olumsuz etkiler.
  • İstekte ve bağımlılık telemetrisinde cihaz modeli eksiktir ve bu durum cihaz kohort analizini olumsuz etkiler.
  • Veritabanı sunucu adı bağımlılık adından çıkarılır ve bu da farklı sunucularda aynı ada sahip tabloları yanlış bir şekilde toplar.

Destek

Destek almak için:

  • Bu makaledeki sorun giderme adımlarını gözden geçirin.
  • Azure desteği sorunlar için bir Azure desteği bileti açın.

OpenTelemetry sorunları için doğrudan OpenTelemetry .NET topluluğuna başvurun.

OpenTelemetry geri bildirimi

Geri bildirim sağlamak için:

Sonraki adımlar