Application Analizler .NET SDK ile özel işlemleri izleme

  • Makale

Uygulama Analizler SDK'ları, HTTP istekleri ve SQL sorguları gibi bağımlı hizmetlere gelen HTTP isteklerini ve çağrılarını otomatik olarak izler. İsteklerin ve bağımlılıkların izlenmesi ve bağıntılanması, bu uygulamayı birleştiren tüm mikro hizmetlerde uygulamanın yanıt hızı ve güvenilirliği hakkında görünürlük sağlar.

Genel olarak desteklenemez bir uygulama desenleri sınıfı vardır. Bu tür desenlerin düzgün izlenmesi için el ile kod izleme gerekir. Bu makale, özel kuyruk işleme ve uzun süre çalışan arka plan görevleri çalıştırma gibi el ile izleme gerektirebilecek birkaç deseni kapsar.

Bu makalede, Uygulama Analizler SDK'sı ile özel işlemleri izleme hakkında yönergeler sağlanır. Bu belgeler aşağıdakiler için geçerlidir:

  • .NET (Temel SDK olarak da bilinir) sürüm 2.4+ için uygulama Analizler.
  • Web uygulamaları (çalışan ASP.NET) sürüm 2.4+ için uygulama Analizler.
  • ASP.NET Core sürüm 2.1+ için uygulama Analizler.

Not

Aşağıdaki belgeler, Uygulama Analizler klasik API'sine dayanır. Uygulama Analizler için uzun vadeli plan, OpenTelemetry kullanarak veri toplamaktır. Daha fazla bilgi için bkz . .NET, Node.js, Python ve Java uygulamaları için Azure İzleyici OpenTelemetry'yi etkinleştirme.

Genel bakış

İşlem, bir uygulama tarafından çalıştırılan mantıksal bir iş parçasıdır. Ad, başlangıç zamanı, süre, sonuç ve kullanıcı adı, özellikler ve sonuç gibi yürütme bağlamı vardır. A işlemi B işlemi tarafından başlatıldıysa, B işlemi A için üst öğe olarak ayarlanır. Bir işlemin yalnızca bir üst öğesi olabilir, ancak birçok alt işlemi olabilir. İşlemler ve telemetri bağıntısı hakkında daha fazla bilgi için bkz. Uygulama Analizler telemetri bağıntısı.

Uygulama Analizler .NET SDK'sında, işlem OperationTelemetry soyut sınıfı ve onun alt öğeleri RequestTelemetry ve DependencyTelemetry tarafından açıklanmıştır.

Gelen işlemleri izleme

Application Analizler web SDK'sı, bir IIS işlem hattında ve tüm ASP.NET Core uygulamalarında çalışan ASP.NET uygulamalar için HTTP isteklerini otomatik olarak toplar. Diğer platformlar ve çerçeveler için topluluk tarafından desteklenen çözümler vardır. Uygulama standart veya topluluk tarafından desteklenen çözümlerden herhangi biri tarafından desteklenmiyorsa, uygulamayı el ile izleyebilirsiniz.

Özel izleme gerektiren bir diğer örnek de kuyruktan öğe alan çalışandır. Bazı kuyruklarda, bu kuyruğa ileti ekleme çağrısı bağımlılık olarak izlenir. İleti işlemeyi açıklayan üst düzey işlem otomatik olarak toplanmaz.

Şimdi bu tür işlemlerin nasıl izlendiğini görelim.

Yüksek düzeyde, görev bilinen özellikleri oluşturmak RequestTelemetry ve ayarlamaktır. İşlem tamamlandıktan sonra telemetriyi izlersiniz. Aşağıdaki örnekte bu görev gösterilmektedir.

Owin şirket içinde barındırılan uygulamada HTTP isteği

Bu örnekte, bağıntı için HTTP Protokolü'ne göre izleme bağlamı yayılır. Burada açıklanan üst bilgileri almayı beklemeniz gerekir.

public class ApplicationInsightsMiddleware : OwinMiddleware
{
    // You may create a new TelemetryConfiguration instance, reuse one you already have,
    // or fetch the instance created by Application Insights SDK.
    private readonly TelemetryConfiguration telemetryConfiguration = TelemetryConfiguration.CreateDefault();
    private readonly TelemetryClient telemetryClient = new TelemetryClient(telemetryConfiguration);
    
    public ApplicationInsightsMiddleware(OwinMiddleware next) : base(next) {}

    public override async Task Invoke(IOwinContext context)
    {
        // Let's create and start RequestTelemetry.
        var requestTelemetry = new RequestTelemetry
        {
            Name = $"{context.Request.Method} {context.Request.Uri.GetLeftPart(UriPartial.Path)}"
        };

        // If there is a Request-Id received from the upstream service, set the telemetry context accordingly.
        if (context.Request.Headers.ContainsKey("Request-Id"))
        {
            var requestId = context.Request.Headers.Get("Request-Id");
            // Get the operation ID from the Request-Id (if you follow the HTTP Protocol for Correlation).
            requestTelemetry.Context.Operation.Id = GetOperationId(requestId);
            requestTelemetry.Context.Operation.ParentId = requestId;
        }

        // StartOperation is a helper method that allows correlation of 
        // current operations with nested operations/telemetry
        // and initializes start time and duration on telemetry items.
        var operation = telemetryClient.StartOperation(requestTelemetry);

        // Process the request.
        try
        {
            await Next.Invoke(context);
        }
        catch (Exception e)
        {
            requestTelemetry.Success = false;
            requestTelemetry.ResponseCode;
            telemetryClient.TrackException(e);
            throw;
        }
        finally
        {
            // Update status code and success as appropriate.
            if (context.Response != null)
            {
                requestTelemetry.ResponseCode = context.Response.StatusCode.ToString();
                requestTelemetry.Success = context.Response.StatusCode >= 200 && context.Response.StatusCode <= 299;
            }
            else
            {
                requestTelemetry.Success = false;
            }

            // Now it's time to stop the operation (and track telemetry).
            telemetryClient.StopOperation(operation);
        }
    }
    
    public static string GetOperationId(string id)
    {
        // Returns the root ID from the '|' to the first '.' if any.
        int rootEnd = id.IndexOf('.');
        if (rootEnd < 0)
            rootEnd = id.Length;

        int rootStart = id[0] == '|' ? 1 : 0;
        return id.Substring(rootStart, rootEnd - rootStart);
    }
}

Bağıntı için HTTP Protokolü de üst bilgiyi bildirir Correlation-Context . Basitlik için burada atlanır.

Kuyruk izleme

Bağıntı için W3C İzleme Bağlamı ve HTTP Protokolü, bağıntı ayrıntılarını HTTP istekleriyle geçirir, ancak her kuyruk protokolü aynı ayrıntıların kuyruk iletisi boyunca nasıl geçirildiğini tanımlamalı. AMQP gibi bazı kuyruk protokolleri daha fazla meta veri geçirilmesine izin verir. Azure Depolama Kuyruğu gibi diğer protokoller, bağlamın ileti yüküne kodlanmış olmasını gerektirir.

Not

Bileşenler arası izleme henüz kuyruklar için desteklenmemektedir.

HTTP ile, üreticiniz ve tüketiciniz farklı Uygulama Analizler kaynaklarına telemetri gönderiyorsa, işlem tanılama deneyimi ve Uygulama Haritası işlemleri gösterir ve uçtan uca eşler. Kuyruklar söz konusu olduğunda, bu özellik henüz desteklenmemektedir.

Service Bus kuyruğu

İzleme bilgileri için bkz . Azure Service Bus mesajlaşması aracılığıyla dağıtılmış izleme ve bağıntı.

Azure Depolama kuyruğu

Aşağıdaki örnekte, Azure Depolama kuyruk işlemlerinin nasıl izlenip üretici, tüketici ve Azure Depolama arasında telemetrinin nasıl ilişkilendirilme işlemi gösterilmektedir.

Depolama kuyruğunun bir HTTP API'si vardır. Kuyruğa yapılan tüm çağrılar HTTP istekleri için Uygulama Analizler Bağımlılık Toplayıcısı tarafından izlenir. ASP.NET ve ASP.NET Core uygulamalarında varsayılan olarak yapılandırılır. Diğer uygulama türlerinde Konsol uygulamaları belgelerine bakın.

Uygulama Analizler işlem kimliğini Depolama istek kimliğiyle ilişkilendirmek de isteyebilirsiniz. Depolama istek istemcisi ve sunucu isteği kimliği ayarlama ve alma hakkında bilgi için bkz. Azure Depolama izleme, tanılama ve sorunlarını giderme.

Enqueue

Depolama kuyrukları HTTP API'sini desteklediğinden, kuyrukla yapılan tüm işlemler Uygulama Analizler tarafından otomatik olarak izlenir. Çoğu durumda, bu izleme yeterli olmalıdır. Tüketici tarafındaki izlemeleri üretici izlemeleriyle ilişkilendirmek için, bağıntı için HTTP Protokolü'nde yaptığımıza benzer bir bağıntı bağlamı geçirmeniz gerekir.

Bu örnekte işlemin nasıl izlenir gösterilmektedir Enqueue . Şunları yapabilirsiniz:

  • Yeniden denemeleri bağıntılı (varsa): Hepsinin ortak bir üst öğesi vardır ve bu işlemdir Enqueue . Aksi takdirde, bunlar gelen isteğin alt öğeleri olarak izlenir. Kuyruğa birden çok mantıksal istek varsa, hangi çağrının yeniden denemelere neden olduğunu bulmak zor olabilir.
  • Depolama günlükleri (gerekirse ve gerektiğinde) ilişkilendirin: Bunlar Uygulama Analizler telemetrisiyle ilişkilendirildi.

İşlem Enqueue , üst işlemin alt öğesidir. Bir örnek, gelen HTTP isteğidir. HTTP bağımlılık çağrısı, işlemin alt öğesi Enqueue ve gelen isteğin torunlarıdır.

public async Task Enqueue(CloudQueue queue, string message)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("enqueue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Enqueue " + queue.Name;

    // MessagePayload represents your custom message and also serializes correlation identifiers into payload.
    // For example, if you choose to pass payload serialized to JSON, it might look like
    // {'RootId' : 'some-id', 'ParentId' : '|some-id.1.2.3.', 'message' : 'your message to process'}
    var jsonPayload = JsonConvert.SerializeObject(new MessagePayload
    {
        RootId = operation.Telemetry.Context.Operation.Id,
        ParentId = operation.Telemetry.Id,
        Payload = message
    });
    
    CloudQueueMessage queueMessage = new CloudQueueMessage(jsonPayload);

    // Add operation.Telemetry.Id to the OperationContext to correlate Storage logs and Application Insights telemetry.
    OperationContext context = new OperationContext { ClientRequestID = operation.Telemetry.Id};

    try
    {
        await queue.AddMessageAsync(queueMessage, null, null, new QueueRequestOptions(), context);
    }
    catch (StorageException e)
    {
        operation.Telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.Telemetry.Success = false;
        operation.Telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

Uygulama raporlarınızın telemetri miktarını azaltmak için veya işlemi başka nedenlerle izlemek Enqueue istemiyorsanız API'yi Activity doğrudan kullanın:

  • Uygulama Analizler işlemini başlatmak yerine yeni Activity bir oluşturma (ve başlatma). İşlem adı dışında üzerinde herhangi bir özellik atamanız gerekmez.
  • yerine ileti yükünü operation.Telemetry.Idseri hale getirmeyourActivity.Id. komutunu da kullanabilirsiniz Activity.Current.Id.

Kuyruktan Çıkarma

benzer şekildeEnqueue, Depolama kuyruğuna yönelik gerçek bir HTTP isteği, Uygulama Analizler tarafından otomatik olarak izlenir. İşlem Enqueue büyük olasılıkla gelen istek bağlamı gibi üst bağlamda gerçekleşir. Uygulama Analizler SDK'ları, bu tür bir işlemi ve HTTP bölümünü, üst istek ve diğer telemetri verilerinin aynı kapsamda bildirildiği şekilde otomatik olarak ilişkilendirilir.

İşlem Dequeue biraz karmaşık. Uygulama Analizler SDK'sı HTTP isteklerini otomatik olarak izler. Ancak ileti ayrıştırılana kadar bağıntı bağlamını bilmez. özellikle birden fazla ileti alındığında, iletiyi almak için HTTP isteğini telemetrinin geri kalanıyla ilişkilendirmek mümkün değildir.

public async Task<MessagePayload> Dequeue(CloudQueue queue)
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>("dequeue " + queue.Name);
    operation.Telemetry.Type = "Azure queue";
    operation.Telemetry.Data = "Dequeue " + queue.Name;
    
    try
    {
        var message = await queue.GetMessageAsync();
    }
    catch (StorageException e)
    {
        operation.telemetry.Properties.Add("AzureServiceRequestID", e.RequestInformation.ServiceRequestID);
        operation.telemetry.Success = false;
        operation.telemetry.ResultCode = e.RequestInformation.HttpStatusCode.ToString();
        telemetryClient.TrackException(e);
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }

    return null;
}

İşlem

Aşağıdaki örnekte, gelen bir ileti gelen HTTP isteğine benzer şekilde izlenir:

public async Task Process(MessagePayload message)
{
    // After the message is dequeued from the queue, create RequestTelemetry to track its processing.
    RequestTelemetry requestTelemetry = new RequestTelemetry { Name = "process " + queueName };
    
    // It might also make sense to get the name from the message.
    requestTelemetry.Context.Operation.Id = message.RootId;
    requestTelemetry.Context.Operation.ParentId = message.ParentId;

    var operation = telemetryClient.StartOperation(requestTelemetry);

    try
    {
        await ProcessMessage();
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        throw;
    }
    finally
    {
        // Update status code and success as appropriate.
        telemetryClient.StopOperation(operation);
    }
}

Benzer şekilde, diğer kuyruk işlemleri de izlenebilir. Bir göz atma işlemi, dequeue işlemine benzer bir şekilde izlenmelidir. Kuyruk yönetimi işlemlerini izleme gerekli değildir. Uygulama Analizler HTTP gibi işlemleri izler ve çoğu durumda yeterlidir.

İleti silme işlemini işaretlerken işlem (bağıntı) tanımlayıcılarını ayarladığınızdan emin olun. Alternatif olarak API'yi Activity kullanabilirsiniz. Ardından, Uygulama Analizler SDK'sı bunu sizin için yaptığı için telemetri öğelerinde işlem tanımlayıcıları ayarlamanız gerekmez:

  • Kuyruktan bir öğe aldıktan sonra yeni Activity bir öğe oluşturun.
  • Tüketici ve üretici günlüklerini ilişkilendirmek için kullanın Activity.SetParentId(message.ParentId) .
  • Activityöğesini başlatın.
  • Yardımcıları kullanarak Start/StopOperation sorguları kaldırma, işleme ve silme işlemlerini izleyin. Bunu aynı zaman uyumsuz denetim akışından (yürütme bağlamı) yapın. Bu şekilde, düzgün bir şekilde bağıntılı olurlar.
  • Activitynu durdurun.
  • Telemetriyi el ile kullanın Start/StopOperation veya çağırabilirsiniz Track .

Bağımlılık türleri

Uygulama Analizler, kullanıcı arabirimi deneyimlerini özelleştirmek için bağımlılık türünü kullanır. Kuyruklar için İşlem tanılama deneyimini geliştiren aşağıdaki türlerini DependencyTelemetry tanır:

  • Azure queueAzure Depolama kuyrukları için
  • Azure Event Hubs Azure Event Hubs için
  • Azure Service Bus Azure Service Bus için

Toplu işleme

Bazı kuyruklarla, tek bir istekle birden çok iletinin sırasını kaldırabilirsiniz. Bu tür iletilerin işlenmesi büyük olasılıkla bağımsızdır ve farklı mantıksal işlemlere aittir. İşlemin işlenmekte olan belirli bir iletiyle bağıntılı Dequeue olması mümkün değildir.

Her ileti kendi zaman uyumsuz denetim akışında işlenmelidir. Daha fazla bilgi için Giden bağımlılıkları izleme bölümüne bakın.

Uzun süre çalışan arka plan görevleri

Bazı uygulamalar, kullanıcı isteklerinin neden olabileceği uzun süre çalışan işlemler başlatır. İzleme/izleme perspektifinden, istek veya bağımlılık izlemesinden farklı değildir:

async Task BackgroundTask()
{
    var operation = telemetryClient.StartOperation<DependencyTelemetry>(taskName);
    operation.Telemetry.Type = "Background";
    try
    {
        int progress = 0;
        while (progress < 100)
        {
            // Process the task.
            telemetryClient.TrackTrace($"done {progress++}%");
        }
        // Update status code and success as appropriate.
    }
    catch (Exception e)
    {
        telemetryClient.TrackException(e);
        // Update status code and success as appropriate.
        throw;
    }
    finally
    {
        telemetryClient.StopOperation(operation);
    }
}

Bu örnekte bağıntı telemetryClient.StartOperation bağlamını oluşturur DependencyTelemetry ve doldurur. İşlemi zamanlayan gelen istekler tarafından oluşturulmuş bir üst işleminiz olduğunu varsayalım. Gelen istekle aynı zaman uyumsuz denetim akışında başladığı sürece BackgroundTask , bu üst işlemle bağıntılıdır. BackgroundTask ve tüm iç içe telemetri öğeleri, istek sona erdikten sonra bile buna neden olan istekle otomatik olarak ilişkilendirilir.

Görev, kendisiyle ilişkilendirilmiş herhangi bir işlemi (Activity) olmayan arka plan iş parçacığından başladığında üst BackgroundTask öğe yoktur. Ancak, iç içe işlemlere sahip olabilir. Görevden bildirilen tüm telemetri öğeleri içinde BackgroundTaskoluşturulan ile DependencyTelemetry ilişkilendirilir.

Giden bağımlılıkları izleme

Kendi bağımlılık türünüzü veya Uygulama Analizler tarafından desteklenmeyen bir işlemi izleyebilirsiniz.

Enqueue Service Bus kuyruğundaki veya Depolama kuyruğundaki yöntem, bu tür özel izleme için örnek olarak kullanılabilir.

Özel bağımlılık izleme için genel yaklaşım:

  • Bağıntı TelemetryClient.StartOperation için gereken özellikleri ve başlangıç, zaman damgası ve süre gibi diğer bazı özellikleri dolduran DependencyTelemetry (uzantı) yöntemini çağırın.
  • üzerinde DependencyTelemetryad ve ihtiyacınız olan diğer bağlam gibi diğer özel özellikleri ayarlayın.
  • Bir bağımlılık çağrısı yapın ve bekleyin.
  • İşlem tamamlandığında ile StopOperation işlemini durdurun.
  • Özel durumları işleme.
public async Task RunMyTaskAsync()
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>("task 1"))
    {
        try 
        {
            var myTask = await StartMyTaskAsync();
            // Update status code and success as appropriate.
        }
        catch(...) 
        {
            // Update status code and success as appropriate.
        }
    }
}

Bir işlemin atılması işlemin durmasına neden olur, bu nedenle çağrısı StopOperationyapmak yerine bunu yapabilirsiniz.

Uyarı

Bazı durumlarda, işlenmeyen bir özel durum çağrılmasını engelleyebilirfinally , bu nedenle işlemler izlenmeyebilir.

Paralel işlemler işleme ve izleme

Çağrısı StopOperation yalnızca başlatılan işlemi durdurur. Geçerli çalışan işlem durdurmak istediğiniz işlemle eşleşmiyorsa hiçbir StopOperation şey yapmaz. Aynı yürütme bağlamında paralel olarak birden çok işlem başlatırsanız bu durum oluşabilir.

var firstOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 1");
var firstTask = RunMyTaskAsync();

var secondOperation = telemetryClient.StartOperation<DependencyTelemetry>("task 2");
var secondTask = RunMyTaskAsync();

await firstTask;

// FAILURE!!! This will do nothing and will not report telemetry for the first operation
// as currently secondOperation is active.
telemetryClient.StopOperation(firstOperation); 

await secondTask;

Paralel çalışan işlemleri yalıtmak için işlemi her zaman aynı zaman uyumsuz yöntemde çağırdığınızdan StartOperation ve işlediğinize emin olun. İşlem zaman uyumluysa (veya zaman uyumsuz değilse), işlemi sarmalayıp ile Task.Runizleyin.

public void RunMyTask(string name)
{
    using (var operation = telemetryClient.StartOperation<DependencyTelemetry>(name))
    {
        Process();
        // Update status code and success as appropriate.
    }
}

public async Task RunAllTasks()
{
    var task1 = Task.Run(() => RunMyTask("task 1"));
    var task2 = Task.Run(() => RunMyTask("task 2"));
    
    await Task.WhenAll(task1, task2);
}

Application Analizler operations vs. System.Diagnostics.Activity

System.Diagnostics.Activity dağıtılmış izleme bağlamını temsil eder ve çerçeveler ve kitaplıklar tarafından işlemin içinde ve dışında bağlam oluşturup yaymak ve telemetri öğelerini ilişkilendirmek için kullanılır. Activity gelen veya giden istekler ve özel durumlar gibi ilginç olayları bildirmek için çerçeve/kitaplık arasında bildirim mekanizması olarak birlikte System.Diagnostics.DiagnosticSource çalışır.

Etkinlikler Uygulama Analizler birinci sınıf vatandaşlardır. Otomatik bağımlılık ve istek koleksiyonu, olaylarla DiagnosticSource birlikte bunlara yoğun bir şekilde güvenir. Uygulamanızda oluşturduysanız Activity Uygulama Analizler telemetrisi oluşturulmaz. Uygulama Analizler telemetriye çevrilmesi Activity için olayları alması DiagnosticSource ve olay adlarını ve yüklerini bilmesi gerekir.

Her Uygulama Analizler işlemi (istek veya bağımlılık) içerirActivity. Çağrıldığında StartOperation , altında oluşturur Activity . StartOperation , istek veya bağımlılık telemetrilerini el ile izlemenin ve her şeyin bağıntılı olduğundan emin olmak için önerilen yoldur.

Sonraki adımlar