Distribuované trasování a korelace prostřednictvím zasílání zpráv služby Service Bus

Automatické odčítání klienta služby Service Bus .NET

Třída ServiceBusProcessor klienta služby Azure Messaging Service Bus pro .NET poskytuje body instrumentace trasování, které je možné připojit pomocí trasovacích systémů nebo kus kódu klienta. Instrumentace umožňuje sledovat všechna volání do služby zasílání zpráv service Bus ze strany klienta. Pokud je zpracování zpráv provedeno pomocí ProcessMessageAsync ServiceBusProcessor (vzor obslužné rutiny zprávy), zpracování zpráv je také instrumentováno.

Sledování pomocí Aplikace Azure lication Insights

Microsoft Application Insights poskytuje bohaté možnosti monitorování výkonu, včetně automatického požadavku a sledování závislostí.

V závislosti na typu projektu nainstalujte sadu Application Insights SDK:

• ASP.NET – instalace verze 2.5-beta2 nebo vyšší
• ASP.NET Core – nainstalujte verzi 2.2.0-beta2 nebo vyšší. Tyto odkazy obsahují podrobnosti o instalaci sady SDK, vytváření prostředků a konfiguraci sady SDK (v případě potřeby). Informace o non-ASP.NET aplikacích najdete v článku Aplikace Azure lication Insights pro konzolové aplikace.

Pokud ke zpracování zpráv používáte ProcessMessageAsync ServiceBusProcessor (vzor obslužné rutiny zpráv), je také instrumentováno zpracování zpráv. Všechna volání služby Service Bus provedená vaší službou se automaticky sledují a korelují s ostatními položkami telemetrie. V opačném případě se podívejte na následující příklad pro sledování ručního zpracování zpráv.

Trasování zpracování zpráv

async Task ProcessAsync(ProcessMessageEventArgs args)
{
    ServiceBusReceivedMessage message = args.Message;
    if (message.ApplicationProperties.TryGetValue("Diagnostic-Id", out var objectId) && objectId is string diagnosticId)
    {
        var activity = new Activity("ServiceBusProcessor.ProcessMessage");
        activity.SetParentId(diagnosticId);
        // If you're using Microsoft.ApplicationInsights package version 2.6-beta or higher, you should call StartOperation<RequestTelemetry>(activity) instead
        using (var operation = telemetryClient.StartOperation<RequestTelemetry>("Process", activity.RootId, activity.ParentId))
        {
            telemetryClient.TrackTrace("Received message");
            try 
            {
            // process message
            }
            catch (Exception ex)
            {
                telemetryClient.TrackException(ex);
                operation.Telemetry.Success = false;
                throw;
            }

            telemetryClient.TrackTrace("Done");
        }
    }
}

V tomto příkladu se hlásí telemetrie požadavků pro každou zpracovanou zprávu, časové razítko, dobu trvání a výsledek (úspěch). Telemetrie má také sadu vlastností korelace. Vnořené trasování a výjimky hlášené během zpracování zpráv jsou také označeny vlastnostmi korelace představujícími je jako "podřízené" objektu RequestTelemetry.

V případě, že během zpracování zpráv voláte podporované externí komponenty, budou se také automaticky sledovat a korelovat. Informace o ručním sledování a korelaci najdete v tématu Sledování vlastních operací pomocí sady Application Insights .NET SDK .

Pokud kromě sady Application Insights SDK spouštíte jakýkoli externí kód, při prohlížení protokolů Application Insights se očekává delší doba trvání .

Neznamená to, že při přijetí zprávy došlo ke zpoždění. V tomto scénáři již byla zpráva přijata, protože zpráva je předána jako parametr kódu sady SDK. A značka názvu v protokolech App Insights (Proces) označuje, že zpráva se teď zpracovává kódem pro zpracování externích událostí. Tento problém nesouvisí s Azure. Místo toho tyto metriky odkazují na efektivitu vašeho externího kódu vzhledem k tomu, že zpráva už byla přijata ze služby Service Bus.

Sledování pomocí OpenTelemetry

Klientská knihovna service Bus .NET verze 7.5.0 a novější podporuje OpenTelemetry v experimentálním režimu. Další informace naleznete v tématu Distribuované trasování v sadě .NET SDK.

Sledování bez trasování systému

V případě, že systém trasování nepodporuje automatické sledování volání služby Service Bus, můžete se podívat na přidání takové podpory do systému trasování nebo do vaší aplikace. Tato část popisuje diagnostické události odeslané klientem .NET služby Service Bus.

Klient .NET service Bus je instrumentovaný pomocí trasování .NET primitives System.Diagnostics.Activity a System.Diagnostics.DiagnosticSource.

Activity slouží jako kontext trasování v době, kdy DiagnosticSource se jedná o mechanismus oznámení.

Pokud pro události DiagnosticSource není žádný naslouchací proces, instrumentace je vypnutá, čímž se zachovají nulové náklady na instrumentaci. DiagnosticSource poskytuje všem ovládacím prvkům naslouchacímu procesu:

• Naslouchací proces řídí, které zdroje a události se mají naslouchat
• Naslouchací proces řídí rychlost událostí a vzorkování.
• události se odesílají s datovou částí, která poskytuje úplný kontext, abyste během události mohli přistupovat k objektu zprávy a upravovat je.

Než budete pokračovat v implementaci, seznamte se s uživatelskou příručkou DiagnosticSource.

Pojďme vytvořit naslouchací proces pro události služby Service Bus v aplikaci ASP.NET Core, která zapisuje protokoly pomocí microsoft.Extension.Loggeru. Používá knihovnu System.Reactive.Core k přihlášení k odběru DiagnosticSource (bez ní se také dá snadno přihlásit k odběru DiagnosticSource).

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory factory, IApplicationLifetime applicationLifetime)
{
    // configuration...

    var serviceBusLogger = factory.CreateLogger("Azure.Messaging.ServiceBus");

    IDisposable innerSubscription = null;
    IDisposable outerSubscription = DiagnosticListener.AllListeners.Subscribe(delegate (DiagnosticListener listener)
    {
        // subscribe to the Service Bus DiagnosticSource
        if (listener.Name == "Azure.Messaging.ServiceBus")
        {
            // receive event from Service Bus DiagnosticSource
            innerSubscription = listener.Subscribe(delegate (KeyValuePair<string, object> evnt)
            {
                // Log operation details once it's done
                if (evnt.Key.EndsWith("Stop"))
                {
                    Activity currentActivity = Activity.Current;
                    serviceBusLogger.LogInformation($"Operation {currentActivity.OperationName} is finished, Duration={currentActivity.Duration}, Id={currentActivity.Id}, StartTime={currentActivity.StartTimeUtc}");
                }
            });
        }
    });

    applicationLifetime.ApplicationStopping.Register(() =>
    {
        outerSubscription?.Dispose();
        innerSubscription?.Dispose();
    });
}

V tomto příkladu naslouchací proces zaznamená dobu trvání, výsledek, jedinečný identifikátor a čas spuštění pro každou operaci Service Bus.

Události

Všechny události budou mít následující vlastnosti, které odpovídají specifikaci otevřené telemetrie: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md.

• message_bus.destination – fronta, téma/ cesta předplatného
• peer.address – plně kvalifikovaný obor názvů
• kind – buď producent, spotřebitel, nebo klient. Producent se používá při odesílání zpráv, příjemce při příjmu a klient při usídlení.
• component – servicebus

Všechny události mají Entity také vlastnosti a Endpoint vlastnosti.

• Entity – – Název entity (fronta, téma atd.)
• Endpoint – Adresa URL koncového bodu služby Service Bus

Instrumentované operace

Tady je úplný seznam instrumentovaných operací:

Filtrování a vzorkování

V některýchpřípadechch Můžete protokolovat pouze události Stop (jako v předchozím příkladu) nebo ukázkové procento událostí. DiagnosticSource poskytnout způsob, jak toho dosáhnout s predikátem IsEnabled . Další informace naleznete v tématu Kontextové filtrování v DiagnosticSource.

IsEnabled může být volána vícekrát pro jednu operaci, aby se minimalizoval dopad na výkon.

IsEnabled je volána v následující sekvenci:

1. IsEnabled(<OperationName>, string entity, null) například IsEnabled("ServiceBusSender.Send", "MyQueue1"). Všimněte si, že na konci není žádná možnost Start ani Stop. Slouží k filtrování konkrétních operací nebo front. Pokud metoda zpětného volání vrátí false, události operace se neodesílají.

   • U operací Process a ProcessSession také obdržíte IsEnabled(<OperationName>, string entity, Activity activity) zpětná volání. Slouží k filtrování událostí na activity.Id základě vlastností značky.

2. IsEnabled(<OperationName>.Start) například IsEnabled("ServiceBusSender.Send.Start"). Zkontroluje, jestli se má aktivovat událost Start. Výsledek ovlivňuje pouze událost Start, ale další instrumentace na ní nezávisí.

IsEnabled Není k dispozici žádná událost Stop.

Pokud je výsledkem operace výjimka, IsEnabled("ServiceBusSender.Send.Exception") je volána. Můžete se přihlásit pouze k odběru událostí výjimky a zabránit zbytku instrumentace. V takovém případě stále musíte tyto výjimky zpracovat. Vzhledem k tomu, že jiná instrumentace je zakázaná, neměli byste očekávat, že kontext trasování bude proudit se zprávami od příjemce k producentovi.

Můžete také použít IsEnabled implementaci strategií vzorkování. Vzorkování na základě nebo Activity.RootId zajištění konzistentního Activity.Id vzorkování napříč všemi pneumatikami (pokud se šíří systémem trasování nebo vlastním kódem).

V přítomnosti více DiagnosticSource naslouchacích procesů pro stejný zdroj stačí, aby událost přijali jenom jeden naslouchací proces, takže neexistuje žádná záruka, která IsEnabled se volá.

30. září 2026 vyřadíme knihovny sady SDK služby Azure Service Bus pro WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus a com.microsoft.azure.servicebus, které nevyhovují pokynům sady Azure SDK. Také ukončíme podporu protokolu SBMP, takže tento protokol už nebudete moct používat po 30. září 2026. Před tímto datem migrujte na nejnovější knihovny sady Azure SDK, které nabízejí důležité aktualizace zabezpečení a vylepšené funkce.

I když starší knihovny je možné používat i po 30. září 2026, nebudou už od Microsoftu dostávat oficiální podporu a aktualizace. Další informace najdete v oznámení o vyřazení podpory.

Automatické odčítání klienta služby Service Bus .NET

Počínaje verzí 3.0.0 Klient Microsoft Azure ServiceBus pro .NET poskytuje body instrumentace trasování, které lze připojit pomocí systémů trasování nebo kus klientského kódu. Instrumentace umožňuje sledovat všechna volání do služby zasílání zpráv service Bus ze strany klienta. Pokud se zpracování zpráv provádí pomocí vzoru obslužné rutiny zprávy, je také instrumentováno zpracování zpráv.

Sledování pomocí Aplikace Azure lication Insights

Microsoft Application Insights poskytuje bohaté možnosti monitorování výkonu, včetně automatického požadavku a sledování závislostí.

V závislosti na typu projektu nainstalujte sadu Application Insights SDK:

• ASP.NET – instalace verze 2.5-beta2 nebo vyšší
• ASP.NET Core – nainstalujte verzi 2.2.0-beta2 nebo vyšší. Tyto odkazy obsahují podrobnosti o instalaci sady SDK, vytváření prostředků a konfiguraci sady SDK (v případě potřeby). Informace o non-ASP.NET aplikacích najdete v článku Aplikace Azure lication Insights pro konzolové aplikace.

Pokud ke zpracování zpráv používáte vzor obslužné rutiny zpráv, máte hotovo: všechna volání služby Service Bus provedená vaší službou se automaticky sledují a korelují s jinými položkami telemetrie. V opačném případě se podívejte na následující příklad pro sledování ručního zpracování zpráv.

Trasování zpracování zpráv

private readonly TelemetryClient telemetryClient;

async Task ProcessAsync(Message message)
{
    var activity = message.ExtractActivity();
    
    // If you're using Microsoft.ApplicationInsights package version 2.6-beta or higher, you should call StartOperation<RequestTelemetry>(activity) instead
    using (var operation = telemetryClient.StartOperation<RequestTelemetry>("Process", activity.RootId, activity.ParentId))
    {
        telemetryClient.TrackTrace("Received message");
        try 
        {
           // process message
        }
        catch (Exception ex)
        {
             telemetryClient.TrackException(ex);
             operation.Telemetry.Success = false;
             throw;
        }

        telemetryClient.TrackTrace("Done");
   }
}

V tomto příkladu RequestTelemetry se hlásí pro každou zpracovanou zprávu s časovým razítkem, dobou trvání a výsledkem (úspěch). Telemetrie má také sadu vlastností korelace. Vnořené trasování a výjimky hlášené během zpracování zpráv jsou také označeny vlastnostmi korelace představujícími je jako "podřízené" objektu RequestTelemetry.

V případě, že během zpracování zpráv voláte podporované externí komponenty, budou se také automaticky sledovat a korelovat. Informace o ručním sledování a korelaci najdete v tématu Sledování vlastních operací pomocí sady Application Insights .NET SDK .

Pokud kromě sady Application Insights SDK spouštíte jakýkoli externí kód, při prohlížení protokolů Application Insights se očekává delší doba trvání .

Neznamená to, že při přijetí zprávy došlo ke zpoždění. V tomto scénáři již byla zpráva přijata, protože zpráva je předána jako parametr kódu sady SDK. A značka názvu v protokolech App Insights (Proces) označuje, že zpráva se teď zpracovává kódem pro zpracování externích událostí. Tento problém nesouvisí s Azure. Místo toho tyto metriky odkazují na efektivitu vašeho externího kódu vzhledem k tomu, že zpráva už byla přijata ze služby Service Bus. Podívejte se na tento soubor na GitHubu a zjistěte, kde se značka Proces generuje a přiřazuje po přijetí zprávy ze služby Service Bus.

Sledování bez trasování systému

V případě, že systém trasování nepodporuje automatické sledování volání služby Service Bus, můžete se podívat na přidání takové podpory do systému trasování nebo do vaší aplikace. Tato část popisuje diagnostické události odeslané klientem .NET služby Service Bus.

Klient .NET service Bus je instrumentovaný pomocí trasování .NET primitives System.Diagnostics.Activity a System.Diagnostics.DiagnosticSource.

Activity slouží jako kontext trasování v době, kdy DiagnosticSource se jedná o mechanismus oznámení.

Pokud pro události DiagnosticSource není žádný naslouchací proces, instrumentace je vypnutá, čímž se zachovají nulové náklady na instrumentaci. DiagnosticSource poskytuje všem ovládacím prvkům naslouchacímu procesu:

• Naslouchací proces řídí, které zdroje a události se mají naslouchat
• Naslouchací proces řídí rychlost událostí a vzorkování.
• události se odesílají s datovou částí, která poskytuje úplný kontext, abyste během události mohli přistupovat k objektu zprávy a upravovat je.

Než budete pokračovat v implementaci, seznamte se s uživatelskou příručkou DiagnosticSource.

Pojďme vytvořit naslouchací proces pro události služby Service Bus v aplikaci ASP.NET Core, která zapisuje protokoly pomocí microsoft.Extension.Loggeru. Používá knihovnu System.Reactive.Core k přihlášení k odběru DiagnosticSource (bez ní se také dá snadno přihlásit k odběru DiagnosticSource).

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory factory, IApplicationLifetime applicationLifetime)
{
    // configuration...

    var serviceBusLogger = factory.CreateLogger("Microsoft.Azure.ServiceBus");

    IDisposable innerSubscription = null;
    IDisposable outerSubscription = DiagnosticListener.AllListeners.Subscribe(delegate (DiagnosticListener listener)
    {
        // subscribe to the Service Bus DiagnosticSource
        if (listener.Name == "Microsoft.Azure.ServiceBus")
        {
            // receive event from Service Bus DiagnosticSource
            innerSubscription = listener.Subscribe(delegate (KeyValuePair<string, object> evnt)
            {
                // Log operation details once it's done
                if (evnt.Key.EndsWith("Stop"))
                {
                    Activity currentActivity = Activity.Current;
                    TaskStatus status = (TaskStatus)evnt.Value.GetProperty("Status");
                    serviceBusLogger.LogInformation($"Operation {currentActivity.OperationName} is finished, Duration={currentActivity.Duration}, Status={status}, Id={currentActivity.Id}, StartTime={currentActivity.StartTimeUtc}");
                }
            });
        }
    });

    applicationLifetime.ApplicationStopping.Register(() =>
    {
        outerSubscription?.Dispose();
        innerSubscription?.Dispose();
    });
}

V tomto příkladu naslouchací proces zaznamená dobu trvání, výsledek, jedinečný identifikátor a čas spuštění pro každou operaci Service Bus.

Události

Pro každou operaci se odesílají dvě události: Start a Stop. S největší pravděpodobností vás zajímají jenom události Stop. Poskytují výsledek operace a počáteční čas a dobu trvání jako vlastnosti aktivity.

Datová část události poskytuje naslouchací proces s kontextem operace, replikuje příchozí parametry rozhraní API a návratovou hodnotu. Datová část události Stop má všechny vlastnosti datové části události Start, takže událost Start můžete úplně ignorovat.

Všechny události mají také vlastnosti Entity a Endpoint.

• string Entity - – Název entity (fronta, téma atd.)
• Uri Endpoint – Adresa URL koncového bodu služby Service Bus

Každá událost Stop má Status vlastnost s TaskStatus asynchronní operací byla dokončena, která je také vynechána v následující tabulce pro zjednodušení.

Tady je úplný seznam instrumentovaných operací:

V každém případě máte přístup Activity.Current , který obsahuje aktuální kontext operace.

Protokolování dalších vlastností

Activity.Current poskytuje podrobný kontext aktuální operace a jejích nadřazených prvků. Další informace najdete v dokumentaci k aktivitám. Instrumentace služby Service Bus poskytuje další informace o tom, co Activity.Current.Tags obsahují MessageId , a SessionId vždy, když jsou k dispozici.

Aktivity, které sledují událost Receive, Peek a ReceiveDeferred, můžou mít RelatedTo také značku. Obsahuje jedinečný seznam Diagnostic-Id(s) zpráv, které byly přijaty v důsledku toho. Taková operace může vést k přijetí několika nesouvisejících zpráv. Také není známo, Diagnostic-Id kdy se operace spustí, takže operace Příjmu by mohly být korelovány s operacemi procesu, které používají pouze tuto značku. Je užitečné při analýze problémů s výkonem zkontrolovat, jak dlouho trvalo přijetí zprávy.

Efektivní způsob, jak protokolovat značky, je iterovat nad nimi, takže přidání značek do předchozího příkladu vypadá takto:

Activity currentActivity = Activity.Current;
TaskStatus status = (TaskStatus)evnt.Value.GetProperty("Status");

var tagsList = new StringBuilder();
foreach (var tags in currentActivity.Tags)
{
    tagsList.Append($", {tags.Key}={tags.Value}");
}

serviceBusLogger.LogInformation($"{currentActivity.OperationName} is finished, Duration={currentActivity.Duration}, Status={status}, Id={currentActivity.Id}, StartTime={currentActivity.StartTimeUtc}{tagsList}");

Filtrování a vzorkování

V některýchpřípadechch Můžete protokolovat pouze události Stop (jako v předchozím příkladu) nebo ukázkové procento událostí. DiagnosticSource poskytnout způsob, jak toho dosáhnout s predikátem IsEnabled . Další informace naleznete v tématu Kontextové filtrování v DiagnosticSource.

IsEnabled může být volána vícekrát pro jednu operaci, aby se minimalizoval dopad na výkon.

IsEnabled je volána v následující sekvenci:

1. IsEnabled(<OperationName>, string entity, null) například IsEnabled("Microsoft.Azure.ServiceBus.Send", "MyQueue1"). Všimněte si, že na konci není žádná možnost Start ani Stop. Slouží k filtrování konkrétních operací nebo front. Pokud metoda zpětného volání vrátí false, události operace se neodesílají.

   • U operací Process a ProcessSession také obdržíte IsEnabled(<OperationName>, string entity, Activity activity) zpětná volání. Slouží k filtrování událostí na activity.Id základě vlastností značky.

2. IsEnabled(<OperationName>.Start) například IsEnabled("Microsoft.Azure.ServiceBus.Send.Start"). Zkontroluje, jestli se má aktivovat událost Start. Výsledek ovlivňuje pouze událost Start, ale další instrumentace na ní nezávisí.

IsEnabled Není k dispozici žádná událost Stop.

Pokud je výsledkem operace výjimka, IsEnabled("Microsoft.Azure.ServiceBus.Exception") je volána. Můžete se přihlásit pouze k odběru událostí výjimky a zabránit zbytku instrumentace. V takovém případě stále musíte tyto výjimky zpracovat. Vzhledem k tomu, že jiná instrumentace je zakázaná, neměli byste očekávat, že kontext trasování bude proudit se zprávami od příjemce k producentovi.

Můžete také použít IsEnabled implementaci strategií vzorkování. Vzorkování na základě nebo Activity.RootId zajištění konzistentního Activity.Id vzorkování napříč všemi pneumatikami (pokud se šíří systémem trasování nebo vlastním kódem).

V přítomnosti více DiagnosticSource naslouchacích procesů pro stejný zdroj stačí, aby událost přijali jenom jeden naslouchací proces, takže neexistuje žádná záruka, která IsEnabled se volá.