Śledzenie operacji niestandardowych za pomocą zestawu SDK platformy .NET usługi Application Insights

2025-04-21

Zestawy SDK usługi Application Insights automatycznie śledzą przychodzące żądania HTTP i wywołania usług zależnych, takie jak żądania HTTP i zapytania SQL. Śledzenie i korelacja żądań i zależności zapewnia wgląd w czas odpowiedzi i niezawodność całej aplikacji we wszystkich mikrousługach łączących tę aplikację.

Istnieje klasa wzorców aplikacji, których nie można ogólnie obsługiwać. Odpowiednie monitorowanie takich wzorców wymaga instrumentacji kodu ręcznego. W tym artykule opisano kilka wzorców, które mogą wymagać instrumentacji ręcznej, takich jak niestandardowe przetwarzanie kolejek i długotrwałe zadania w tle.

Ten artykuł zawiera wskazówki dotyczące śledzenia operacji niestandardowych za pomocą zestawu SDK usługi Application Insights. Ta dokumentacja jest odpowiednia dla:

Usługa Application Insights dla platformy .NET (znana również jako podstawowy zestaw SDK) w wersji 2.4 lub nowszej.
Usługa Application Insights dla aplikacji internetowych (z systemem ASP.NET) w wersji 2.4 lub nowszej.
Usługa Application Insights dla ASP.NET Core w wersji 2.1 lub nowszej.

Uwaga

Zalecamy stosowanie Azure Monitor OpenTelemetry Distro dla nowych aplikacji lub klientów, aby wspierać działanie usługi Azure Monitor Application Insights. Dystrybucja OpenTelemetry dla Azure Monitor zapewnia podobną funkcjonalność i doświadczenie jak SDK dla Azure Application Insights. Migracja z zestawu SDK usługi Application Insights jest możliwa przy użyciu przewodników migracji dla platformy .NET, Node.js i języka Python, ale nadal pracujemy nad dodaniem kilku dodatkowych funkcji w celu zapewnienia zgodności z poprzednimi wersjami.

Omówienie

Operacja jest logicznym elementem pracy uruchamianym przez aplikację. Ma on nazwę, czas rozpoczęcia, czas trwania, wynik i kontekst wykonywania, taki jak nazwa użytkownika, właściwości i wynik. Jeśli operacja A została zainicjowana przez operację B, operacja B zostaje przypisana jako rodzic dla A. Operacja może mieć tylko jednego rodzica, ale może mieć wiele operacji podrzędnych. Aby uzyskać więcej informacji na temat operacji i korelacji telemetrii, zobacz Korelacja telemetrii usługi Application Insights.

W zestawie SDK platformy .NET usługi Application Insights operacja jest opisana przez abstrakcyjną klasę OperationTelemetry i jej elementy potomne RequestTelemetry i DependencyTelemetry.

Śledzenie operacji przychodzących

Webowy zestaw SDK usługi Application Insights automatycznie zbiera żądania HTTP dla aplikacji ASP.NET uruchamianych w potoku IIS i wszystkich aplikacji ASP.NET Core. Istnieją rozwiązania obsługiwane przez społeczność dla innych platform i struktur. Jeśli aplikacja nie jest obsługiwana przez żadne ze standardowych rozwiązań lub rozwiązań wspieranych przez społeczność, możesz ją zainstrumentować ręcznie.

Innym przykładem, który wymaga niestandardowego śledzenia, jest pracownik, który odbiera elementy z kolejki. W przypadku niektórych kolejek wywołanie funkcji dodawania komunikatu do tej kolejki jest monitorowane jako zależność. Operacja wysokiego poziomu, która opisuje przetwarzanie komunikatów, nie jest automatycznie zbierana.

Zobaczmy, jak można śledzić takie operacje.

Na wysokim poziomie zadaniem jest utworzenie RequestTelemetry i ustawienie znanych właściwości. Po zakończeniu operacji można śledzić dane telemetryczne. W poniższym przykładzie pokazano to zadanie.

Żądanie HTTP w aplikacji hostowanej samodzielnie przez firmę Owin

W tym przykładzie kontekst śledzenia jest propagowany zgodnie z protokołem HTTP dla korelacji. Należy spodziewać się otrzymania nagłówków, które zostały tam opisane.

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

Protokół HTTP dla korelacji również deklaruje nagłówek Correlation-Context. Pominięto go tutaj dla uproszczenia.

Narzędzia monitorowania kolejki

Kontekst śledzenia W3C i protokół HTTP do korelacji przekazują szczegóły korelacyjne z żądaniami HTTP, ale każdy protokół kolejki musi określić, jak te same szczegóły są przekazywane w komunikacie kolejki. Niektóre protokoły kolejki, takie jak AMQP, umożliwiają przekazywanie większej liczby metadanych. Inne protokoły, takie jak kolejka usługi Azure Storage, wymagają kodowania kontekstu w ładunku komunikatu.

Uwaga

Śledzenie międzykomponentowe nie jest jeszcze obsługiwane dla kolejek.

W przypadku protokołu HTTP, jeśli producent i odbiorca wysyłają dane telemetryczne do różnych zasobów usługi Application Insights, doświadczenie w diagnostyce transakcji i Application Map pokazują transakcje oraz mapę end-to-end. W przypadku kolejek ta funkcja nie jest jeszcze obsługiwana.

Kolejka usługi Service Bus

Aby uzyskać informacje o śledzeniu, zobacz Śledzenie rozproszone i korelacja za pośrednictwem komunikatów usługi Azure Service Bus.

Kolejka usługi Azure Storage

W poniższym przykładzie pokazano, jak śledzić operacje kolejki usługi Azure Storage i korelować dane telemetryczne między producentem, konsumentem i usługą Azure Storage.

Kolejka usługi Storage ma interfejs API HTTP. Wszystkie wywołania kolejki są śledzone przez moduł zbierający zależności usługi Application Insights dla żądań HTTP. Jest ona domyślnie konfigurowana w aplikacjach ASP.NET i ASP.NET Core. W przypadku innych rodzajów aplikacji zapoznaj się z dokumentacją aplikacji konsolowych.

Możesz również skorelować identyfikator operacji usługi Application Insights z identyfikatorem żądania magazynu. Aby uzyskać informacje na temat ustawiania i pobierania klienta żądania magazynu oraz identyfikatora żądania serwera, zobacz Monitorowanie, diagnozowanie i rozwiązywanie problemów z usługą Azure Storage.

Kolejka

Ponieważ kolejki usługi Storage obsługują interfejs API HTTP, wszystkie operacje z kolejką są automatycznie śledzone przez usługę Application Insights. W wielu przypadkach instrumentacja ta powinna wystarczyć. Aby skorelować ślady po stronie konsumenta ze śladami producenta, należy przekazać jakiś kontekst korelacji podobnie do tego, jak robimy to w protokole HTTP dla korelacji.

W tym przykładzie pokazano, jak śledzić operację Enqueue . Masz następujące możliwości:

Koreluj ponawianie prób (jeśli istnieje): wszystkie mają jeden wspólny element nadrzędny, który jest operacją Enqueue . W przeciwnym razie są one śledzone jako elementy podrzędne przychodzącego żądania. Jeśli w kolejce znajduje się wiele logicznych zapytań, może być trudno znaleźć zapytanie, które spowodowało ponowne próby.
Skoreluj dzienniki magazynu (w razie potrzeby): są one skorelowane z telemetrią usługi Application Insights.

Operacja Enqueue jest elementem podrzędnym operacji nadrzędnej. Przykładem jest przychodzące żądanie HTTP. Wywołanie zależności HTTP jest elementem składowym operacji Enqueue i wnukiem żądania przychodzącego.

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

Aby zmniejszyć ilość danych telemetrycznych, które raportuje aplikacja, lub jeśli nie chcesz śledzić Enqueue operacji z innych powodów, użyj interfejsu Activity API bezpośrednio.

Utwórz (i uruchom) nową Activity zamiast rozpoczynać operację Application Insights. Nie trzeba przypisywać żadnych właściwości z wyjątkiem nazwy operacji.
Serializuj yourActivity.Id do ładunku wiadomości zamiast operation.Telemetry.Id. Możesz również użyć Activity.Current.Id.

Usuwanie z kolejki

Podobnie jak Enqueuew przypadku usługi Application Insights, rzeczywiste żądanie HTTP do kolejki usługi Storage jest automatycznie śledzone przez usługę Application Insights. Operacja Enqueue prawdopodobnie odbywa się w kontekście nadrzędnym, takim jak kontekst żądania przychodzącego. Zestawy SDK usługi Application Insights automatycznie skorelują taką operację i jej część HTTP z żądaniem nadrzędnym i innymi danymi telemetrycznymi zgłoszonymi w tym samym zakresie.

Operacja Dequeue jest trudna. Zestaw SDK usługi Application Insights automatycznie śledzi żądania HTTP. Nie wie jednak kontekstu korelacji, dopóki komunikat nie zostanie przeanalizowany. Nie można skorelować żądania HTTP w celu pobrania komunikatu z pozostałą częścią telemetrii, zwłaszcza w przypadku odebrania więcej niż jednego komunikatu.

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;
}

Przetwarzaj

W poniższym przykładzie komunikat przychodzący jest śledzony w sposób podobny do przychodzącego żądania HTTP:

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

Podobnie można monitorować inne operacje w kolejce. Operację "peek" należy instrumentować w podobny sposób jak operację "dequeue". Instrumentacja operacji zarządzania kolejkami nie jest konieczna. Usługa Application Insights śledzi operacje, takie jak HTTP, a w większości przypadków wystarczy.

Podczas instrumentowania usuwania komunikatów upewnij się, że ustawiono identyfikatory operacji (korelacji). Alternatywnie możesz użyć interfejsu Activity API. Następnie nie musisz ustawiać identyfikatorów operacji na elementach telemetrii, ponieważ zestaw SDK usługi Application Insights wykonuje następujące czynności:

Utwórz nowy Activity element po utworzeniu elementu z kolejki.
Użyj Activity.SetParentId(message.ParentId) do korelowania dzienników konsumentów i producentów.
Uruchom plik Activity.
Śledź operacje usuwania z kolejki, przetwarzania i usuwania przy użyciu pomocników Start/StopOperation. Zrób to w ramach tego samego asynchronicznego przepływu sterowania, kontekstu wykonywania. W ten sposób są one prawidłowo skorelowane.
Zatrzymaj element Activity.
Użyj Start/StopOperation lub ręcznie wywołaj Track telemetrycznie.

Typy zależności

Usługa Application Insights używa typu zależności do dostosowywania środowisk interfejsu użytkownika. Rozpoznaje następujące typy DependencyTelemetry, które poprawiają doświadczenie diagnostyki transakcji w przypadku kolejek.

Azure queue dla kolejek usługi Azure Storage
Azure Event Hubs dla usługi Azure Event Hubs
Azure Service Bus dla usługi Azure Service Bus

Przetwarzanie wsadowe

W przypadku niektórych kolejek można pobrać lub przetworzyć wiele komunikatów jednym żądaniem. Przetwarzanie takich komunikatów jest prawdopodobnie niezależne i należy do różnych operacji logicznych. Nie można skorelować Dequeue operacji z przetwarzanym konkretnym komunikatem.

Każdy komunikat powinien być przetwarzany we własnym asynchronicznym przepływie sterowania. Aby uzyskać więcej informacji, zobacz sekcję Śledzenie zależności wychodzących.

Długotrwałe zadania w tle

Niektóre aplikacje uruchamiają długotrwałe operacje, które mogą być spowodowane żądaniami użytkowników. Z perspektywy śledzenia/instrumentacji nie różni się ona od instrumentacji żądań lub zależności:

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

W tym przykładzie telemetryClient.StartOperation tworzy DependencyTelemetry i wypełnia kontekst korelacji. Załóżmy, że masz operację nadrzędną, która została utworzona przez przychodzące żądania, które planowały operację. Tak długo, jak BackgroundTask rozpoczyna się w tym samym asynchronicznym przepływie sterowania co żądanie przychodzące, jest powiązany z tą operacją nadrzędną. BackgroundTask i wszystkie zagnieżdżone elementy telemetrii są automatycznie skorelowane z żądaniem, które je wywołało, nawet po zakończeniu żądania.

Gdy zadanie rozpoczyna się od wątku w tle, który nie ma żadnej operacji (Activity) skojarzonej z nim, BackgroundTask nie ma żadnego elementu nadrzędnego. Może jednak mieć zagnieżdżone operacje. Wszystkie elementy telemetrii zgłoszone z zadania są skorelowane z utworzonym elementem DependencyTelemetry w programie BackgroundTask.

Śledzenie zależności wychodzących

Możesz śledzić własny rodzaj zależności lub operację, która nie jest obsługiwana przez usługę Application Insights.

Metoda Enqueue w kolejce Service Bus lub Storage może służyć jako przykład takiego śledzenia niestandardowego.

Ogólne podejście do niestandardowego śledzenia zależności polega na:

Wywołaj metodę TelemetryClient.StartOperation (extension), która wypełnia DependencyTelemetry właściwości wymagane do korelacji i innych właściwości, takich jak start, sygnatura czasowa i czas trwania.
Ustaw inne właściwości niestandardowe na DependencyTelemetry, takie jak nazwa i dowolny inny kontekst, którego potrzebujesz.
Utwórz wywołanie zależności i poczekaj na to.
Zatrzymaj operację StopOperation po jej zakończeniu.
Obsługa wyjątków

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.
        }
    }
}

Usuwanie operacji powoduje zatrzymanie operacji, więc można to zrobić zamiast wywoływać StopOperation.

Ostrzeżenie

W niektórych przypadkach nieobsługiwany wyjątek może uniemożliwić finally wywoływanie, więc operacje mogą nie być śledzone.

Przetwarzanie i śledzenie operacji równoległych

Wywołanie StopOperation zatrzymuje tylko uruchomioną operację. Jeśli bieżąca operacja nie pasuje do tej, którą chcesz zatrzymać, StopOperation nic nie robi. Taka sytuacja może wystąpić, jeśli równolegle uruchomisz wiele operacji w tym samym kontekście wykonywania.

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;

Upewnij się, że zawsze wywołujesz StartOperation i przetwarzasz operację w tej samej asynchronicznej metodzie, aby odizolować równolegle uruchomione operacje. Jeśli operacja jest synchroniczna (lub nie asynchroniczna), opakuj proces i śledź za pomocą polecenia Task.Run.

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

Operacje w ApplicationInsights kontra System.Diagnostics.Activity

System.Diagnostics.Activity reprezentuje kontekst śledzenia rozproszonego i jest używany przez struktury i biblioteki do tworzenia i propagowania kontekstu wewnątrz i poza procesem oraz korelowania elementów telemetrii. Activity współpracuje z System.Diagnostics.DiagnosticSource jako mechanizm powiadamiania między frameworkiem a biblioteką, aby powiadomić o interesujących zdarzeniach, takich jak przychodzące lub wychodzące żądania i wyjątki.

Działania są obywatelami pierwszej klasy w usłudze Application Insights. Automatyczne zależności i zbieranie żądań polegają na nich w dużym stopniu wraz ze zdarzeniami DiagnosticSource . Jeśli utworzono Activity aplikację, nie spowoduje to utworzenia telemetrii usługi Application Insights. Usługa Application Insights musi odbierać DiagnosticSource zdarzenia i znać nazwy zdarzeń i ładunki, aby przetłumaczyć je Activity na dane telemetryczne.

Każda operacja usługi Application Insights (żądanie lub zależność) obejmuje Activity. Gdy StartOperation jest wywoływany, tworzy Activity pod spodem. StartOperation to zalecany sposób ręcznego śledzenia telemetrii żądań lub zależności i upewnienia się, że wszystko jest skorelowane.

Następne kroki

Poznaj podstawy korelacji telemetrii w usłudze Application Insights.
Sprawdź, czy używasz obsługiwanej wersji zestawu SDK usługi Application Insights.
Sprawdź, jak skorelowane dane zasilają środowisko diagnostyki transakcji i mapę aplikacji.
Zobacz model danych dla typów usługi Application Insights i modelu danych.
Zgłaszanie zdarzeń niestandardowych i metryk do usługi Application Insights.
Zapoznaj się ze standardową konfiguracją kolekcji właściwości kontekstu.
Zapoznaj się z podręcznikiem użytkownika System.Diagnostics.Activity, aby zobaczyć, jak korelujemy dane telemetryczne.