Samla in en distribuerad spårning

Artikel
05/09/2023

Den här artikeln gäller för: ✔️ .NET Core 2.1 och senare versioner ✔️ .NET Framework 4.5 och senare versioner

Instrumenterad kod kan skapa Activity objekt som en del av en distribuerad spårning, men informationen i dessa objekt måste samlas in i centraliserad lagring så att hela spårningen kan granskas senare. I den här självstudien samlar du in den distribuerade spårningstelemetrin på olika sätt så att den är tillgänglig för att diagnostisera programproblem vid behov. Se självstudien om instrumentation om du behöver lägga till ny instrumentation.

Samla in spårningar med OpenTelemetry

OpenTelemetry är ett leverantörsneutralt projekt med öppen källkod som stöds av Cloud Native Computing Foundation som syftar till att standardisera generering och insamling av telemetri för molnbaserad programvara. I de här exemplen samlar du in och visar distribuerad spårningsinformation i konsolen. Information om hur du konfigurerar OpenTelemetry för att skicka information någon annanstans finns i komma igång-guiden för OpenTelemetry.

ASP.NET exempel

Krav

.NET Core 7.0 SDK eller en senare version

Skapa ett exempelprogram

Skapa först en ny ASP.NET webbapp som ska användas som demoapp.

dotnet new webapp

Den här appen visar en webbsida, men ingen distribuerad spårningsinformation samlas in ännu om vi bläddrar på webbsidan.

Konfigurera samling

Om du vill använda OpenTelemetry måste du lägga till referenser till flera NuGet-paket.

dotnet add package OpenTelemetry --version 1.4.0-rc1
dotnet add package OpenTelemetry.Exporter.Console --version 1.4.0-rc1
dotnet add package OpenTelemetry.Extensions.Hosting --version 1.4.0-rc1
dotnet add package OpenTelemetry.Instrumentation.AspNetCore --version 1.0.0-rc9.10

Anteckning

När det skrevs var version 1.4.0 Release Candidate 1 den senaste versionen av OpenTelemetry tillgänglig. När en slutlig version är tillgänglig använder du den i stället.

Ändra sedan källkoden i Program.cs så att den ser ut så här:

using OpenTelemetry;
using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddRazorPages();
builder.Services.AddOpenTelemetry()
    .WithTracing(builder =>
    {
        builder.AddAspNetCoreInstrumentation();
        builder.AddConsoleExporter();
    }).StartWithHost();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Kör appen och använd en webbläsare för att bläddra till den webbsida som värdhanteras. Nu när du har aktiverat distribuerad OpenTelemetry-spårning bör du se information om webbläsarwebbbegäranden som skrivs ut till konsolen:

Activity.TraceId:            9c4519ce65a667280daedb3808d376f0
Activity.SpanId:             727c6a8a6cff664f
Activity.TraceFlags:         Recorded
Activity.ActivitySourceName: Microsoft.AspNetCore
Activity.DisplayName:        /
Activity.Kind:               Server
Activity.StartTime:          2023-01-08T01:56:05.4529879Z
Activity.Duration:           00:00:00.1048255
Activity.Tags:
    net.host.name: localhost
    net.host.port: 5163
    http.method: GET
    http.scheme: http
    http.target: /
    http.url: http://localhost:5163/
    http.flavor: 1.1
    http.user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/108.0.0.0 Safari/537.36 Edg/108.0.1462.76
    http.status_code: 200
Resource associated with Activity:
    service.name: unknown_service:demo

All OpenTelemetry-konfiguration sker i de nya källraderna som börjar med builder.Services.AddOpenTelemetry(). Du använde .WithTracing(...) för att aktivera distribuerad spårning. AddAspNetCoreInstrumentation()aktiverat OpenTelemetry för att samla in alla distribuerade spårningsaktiviteter som produceras av ASP.NET Core-webbservern och AddConsoleExporter() instruerar OpenTelemetry att skicka informationen till konsolen. För en mindre trivial app kan du lägga till fler instrumentationsbibliotek för att även samla in spårning för databasfrågor eller utgående HTTP-begäranden. Du skulle också ersätta konsolexportören med en exportör för Jaeger, Zipken eller en annan övervakningstjänst som du har valt att använda.

Exempel på konsolapp

Krav

.NET Core 2.1 SDK eller en senare version

Skapa ett exempelprogram

Innan du kan samla in distribuerad spårningstelemetri måste du skapa den. Ofta finns den här instrumentationen i bibliotek, men för enkelhetens skull skapar du en liten app som har exempelinstrumentation med hjälp av StartActivity. Nu har ingen samling gjorts och StartActivity() har ingen bieffekt och returnerar null. Mer information finns i självstudien om instrumentation .

dotnet new console

Program som riktar in sig på .NET 5 och senare har redan de nödvändiga distribuerade spårnings-API:erna inkluderade. För appar som riktar sig till äldre .NET-versioner lägger du till NuGet-paketet System.Diagnostics.DiagnosticSource version 5 eller senare.

dotnet add package System.Diagnostics.DiagnosticSource

Ersätt innehållet i den genererade Program.cs med den här exempelkällan:

using System;
using System.Diagnostics;
using System.Threading.Tasks;

namespace Sample.DistributedTracing
{
    class Program
    {
        static ActivitySource s_source = new ActivitySource("Sample.DistributedTracing");

        static async Task Main(string[] args)
        {
            await DoSomeWork();
            Console.WriteLine("Example work done");
        }

        static async Task DoSomeWork()
        {
            using (Activity a = s_source.StartActivity("SomeWork"))
            {
                await StepOne();
                await StepTwo();
            }
        }

        static async Task StepOne()
        {
            using (Activity a = s_source.StartActivity("StepOne"))
            {
                await Task.Delay(500);
            }
        }

        static async Task StepTwo()
        {
            using (Activity a = s_source.StartActivity("StepTwo"))
            {
                await Task.Delay(1000);
            }
        }
    }
}

Om du kör appen samlas inga spårningsdata in ännu:

> dotnet run
Example work done

Konfigurera samling

Lägg till NuGet-paketet OpenTelemetry.Exporter.Console .

dotnet add package OpenTelemetry.Exporter.Console

Uppdatera Program.cs med ytterligare OpenTelemetry-direktiv using :

using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;
using System;
using System.Diagnostics;
using System.Threading.Tasks;

Uppdatera Main() för att skapa OpenTelemetry TracerProvider:

        public static async Task Main()
        {
            using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MySample"))
                .AddSource("Sample.DistributedTracing")
                .AddConsoleExporter()
                .Build();

            await DoSomeWork();
            Console.WriteLine("Example work done");
        }

Nu samlar appen in distribuerad spårningsinformation och visar den för konsolen:

> dotnet run
Activity.Id:          00-7759221f2c5599489d455b84fa0f90f4-6081a9b8041cd840-01
Activity.ParentId:    00-7759221f2c5599489d455b84fa0f90f4-9a52f72c08a9d447-01
Activity.DisplayName: StepOne
Activity.Kind:        Internal
Activity.StartTime:   2021-03-18T10:46:46.8649754Z
Activity.Duration:    00:00:00.5069226
Resource associated with Activity:
    service.name: MySample
    service.instance.id: 909a4624-3b2e-40e4-a86b-4a2c8003219e

Activity.Id:          00-7759221f2c5599489d455b84fa0f90f4-d2b283db91cf774c-01
Activity.ParentId:    00-7759221f2c5599489d455b84fa0f90f4-9a52f72c08a9d447-01
Activity.DisplayName: StepTwo
Activity.Kind:        Internal
Activity.StartTime:   2021-03-18T10:46:47.3838737Z
Activity.Duration:    00:00:01.0142278
Resource associated with Activity:
    service.name: MySample
    service.instance.id: 909a4624-3b2e-40e4-a86b-4a2c8003219e

Activity.Id:          00-7759221f2c5599489d455b84fa0f90f4-9a52f72c08a9d447-01
Activity.DisplayName: SomeWork
Activity.Kind:        Internal
Activity.StartTime:   2021-03-18T10:46:46.8634510Z
Activity.Duration:    00:00:01.5402045
Resource associated with Activity:
    service.name: MySample
    service.instance.id: 909a4624-3b2e-40e4-a86b-4a2c8003219e

Example work done

Källor

I exempelkoden anropade AddSource("Sample.DistributedTracing") du så att OpenTelemetry skulle avbilda de aktiviteter som skapats av ActivitySource som redan fanns i koden:

static ActivitySource s_source = new ActivitySource("Sample.DistributedTracing");

Telemetri från valfri ActivitySource kan samlas in genom att anropa AddSource() med källans namn.

Exportörer

Konsolexportören är användbar för snabba exempel eller lokal utveckling, men i en produktionsdistribution vill du förmodligen skicka spårningar till ett centraliserat arkiv. OpenTelemetry stöder olika mål med olika exportörer. Mer information om hur du konfigurerar OpenTelemetry finns i komma igång-guiden för OpenTelemetry.

Samla in spårningar med Application Insights

Telemetri för distribuerad spårning samlas automatiskt in när du har konfigurerat Application Insights SDK för ASP.NET eller ASP.NET Core appar eller genom att aktivera kodlös instrumentering.

Mer information finns i dokumentationen om distribuerad spårning i Application Insights.

Anteckning

För närvarande stöder Application Insights endast insamling av specifika välkända aktivitetsinstrumentation och ignorerar nya användartillkomna aktiviteter. Application Insights erbjuder TrackDependency som ett leverantörsspecifikt API för att lägga till anpassad distribuerad spårningsinformation.

Samla in spårningar med anpassad logik

Utvecklare kan skapa en egen anpassad samlingslogik för aktivitetsspårningsdata. Det här exemplet samlar in telemetrin med hjälp av API:et System.Diagnostics.ActivityListener som tillhandahålls av .NET och skriver ut den till konsolen.

Krav

.NET Core 2.1 SDK eller en senare version

Skapa ett exempelprogram

Först skapar du ett exempelprogram som har distribuerade spårningsinstrumentation men inga spårningsdata samlas in.

dotnet new console

dotnet add package System.Diagnostics.DiagnosticSource

Ersätt innehållet i den genererade Program.cs med den här exempelkällan:

using System;
using System.Diagnostics;
using System.Threading.Tasks;

namespace Sample.DistributedTracing
{
    class Program
    {
        static ActivitySource s_source = new ActivitySource("Sample.DistributedTracing");

        static async Task Main(string[] args)
        {
            await DoSomeWork();
            Console.WriteLine("Example work done");
        }

        static async Task DoSomeWork()
        {
            using (Activity a = s_source.StartActivity("SomeWork"))
            {
                await StepOne();
                await StepTwo();
            }
        }

        static async Task StepOne()
        {
            using (Activity a = s_source.StartActivity("StepOne"))
            {
                await Task.Delay(500);
            }
        }

        static async Task StepTwo()
        {
            using (Activity a = s_source.StartActivity("StepTwo"))
            {
                await Task.Delay(1000);
            }
        }
    }
}

Om du kör appen samlas inga spårningsdata in ännu:

> dotnet run
Example work done

Lägg till kod för att samla in spårningarna

Uppdatera Main() med den här koden:

        static async Task Main(string[] args)
        {
            Activity.DefaultIdFormat = ActivityIdFormat.W3C;
            Activity.ForceDefaultIdFormat = true;

            Console.WriteLine("         {0,-15} {1,-60} {2,-15}", "OperationName", "Id", "Duration");
            ActivitySource.AddActivityListener(new ActivityListener()
            {
                ShouldListenTo = (source) => true,
                Sample = (ref ActivityCreationOptions<ActivityContext> options) => ActivitySamplingResult.AllDataAndRecorded,
                ActivityStarted = activity => Console.WriteLine("Started: {0,-15} {1,-60}", activity.OperationName, activity.Id),
                ActivityStopped = activity => Console.WriteLine("Stopped: {0,-15} {1,-60} {2,-15}", activity.OperationName, activity.Id, activity.Duration)
            });

            await DoSomeWork();
            Console.WriteLine("Example work done");
        }

Utdata innehåller nu loggning:

> dotnet run
         OperationName   Id                                                           Duration
Started: SomeWork        00-bdb5faffc2fc1548b6ba49a31c4a0ae0-c447fb302059784f-01
Started: StepOne         00-bdb5faffc2fc1548b6ba49a31c4a0ae0-a7c77a4e9a02dc4a-01
Stopped: StepOne         00-bdb5faffc2fc1548b6ba49a31c4a0ae0-a7c77a4e9a02dc4a-01      00:00:00.5093849
Started: StepTwo         00-bdb5faffc2fc1548b6ba49a31c4a0ae0-9210ad536cae9e4e-01
Stopped: StepTwo         00-bdb5faffc2fc1548b6ba49a31c4a0ae0-9210ad536cae9e4e-01      00:00:01.0111847
Stopped: SomeWork        00-bdb5faffc2fc1548b6ba49a31c4a0ae0-c447fb302059784f-01      00:00:01.5236391
Example work done

Inställning DefaultIdFormat och ForceDefaultIdFormat är valfritt, men hjälper till att säkerställa att exemplet genererar liknande utdata på olika .NET-körningsversioner. .NET 5 använder W3C TraceContext ID-format som standard, men tidigare .NET-versioner använder Hierarchical som standard ID-format. Mer information finns i Aktivitets-ID:t.

System.Diagnostics.ActivityListener används för att ta emot återanrop under en aktivitets livslängd.

ShouldListenTo - Varje aktivitet är associerad med en ActivitySource, som fungerar som dess namnområde och producent. Återanropet anropas en gång för varje ActivitySource i processen. Returnera sant om du är intresserad av att utföra sampling eller bli meddelad om start-/stopphändelser för aktiviteter som skapats av den här källan.
Sample - Som standard StartActivity skapar inte ett aktivitetsobjekt om inte någon ActivityListener anger att det ska samplas. AllDataAndRecorded Retur anger att aktiviteten ska skapas, IsAllDataRequested ska anges till true och ActivityTraceFlags att flaggan ska Recorded anges. IsAllDataRequested kan observeras av den instrumenterade koden som ett tips om att en lyssnare vill se till att extra aktivitetsinformation som taggar och händelser fylls i. Flaggan Registrerad kodas i W3C TraceContext-ID:t och är ett tips för andra processer som ingår i den distribuerade spårningen att den här spårningen ska samplas.
ActivityStarted och ActivityStopped anropas när en aktivitet startas respektive stoppas. Dessa återanrop ger möjlighet att registrera relevant information om aktiviteten eller eventuellt ändra den. När en aktivitet precis har startat kan mycket av data fortfarande vara ofullständiga och de fylls i innan aktiviteten stoppas.

När en ActivityListener har skapats och återanropen har fyllts i initierar anropet ActivitySource.AddActivityListener(ActivityListener) återanropet. Anropa ActivityListener.Dispose() för att stoppa flödet av återanrop. Tänk på att i kod med flera trådar kan motringningsmeddelanden som pågår tas emot när Dispose() de körs eller till och med strax efter att de har returnerats.

Dela via

Samla in en distribuerad spårning

Samla in spårningar med OpenTelemetry

ASP.NET exempel

Krav

Skapa ett exempelprogram

Konfigurera samling

Exempel på konsolapp

Krav

Skapa ett exempelprogram

Konfigurera samling

Källor

Exportörer

Samla in spårningar med Application Insights

Samla in spårningar med anpassad logik

Krav

Skapa ett exempelprogram

Lägg till kod för att samla in spårningarna

Ytterligare resurser