Lägga till, ändra och filtrera OpenTelemetry

  • Artikel

Den här artikeln innehåller vägledning om hur du lägger till, ändrar och filtrerar OpenTelemetry för program med Hjälp av Azure Monitor Application Insights.

Mer information om OpenTelemetry-begrepp finns i OpenTelemetry-översikten eller Vanliga frågor och svar om OpenTelemetry.

Automatisk datainsamling

Distributionerna samlar automatiskt in data genom att paketera OpenTelemetry-instrumentationsbibliotek.

Inkluderade instrumentationsbibliotek

Begäranden

Beroenden

Loggning

  • ILogger

Mer information om ILoggerfinns i Loggning i C# och .NET och kodexempel.

Fotnoter

  • ¹: Stöder automatisk rapportering av ohanterade/ohanterade undantag
  • ²: Stöder OpenTelemetry-mått
  • ³: Som standard samlas loggning endast in på INFO-nivå eller högre. Information om hur du ändrar den här inställningen finns i konfigurationsalternativen.
  • ⁴: Som standard samlas loggning endast in när loggningen utförs på VARNING-nivån eller högre.

Kommentar

Azure Monitor OpenTelemetry Distros innehåller anpassad mappning och logik för att automatiskt generera Application Insights-standardmått.

Dricks

Alla OpenTelemetry-mått oavsett om de samlas in automatiskt från instrumentationsbibliotek eller samlas in manuellt från anpassad kodning anses för närvarande vara Application Insights "anpassade mått" för faktureringsändamål. Läs mer.

Lägga till ett bibliotek för communityinstrumentation

Du kan samla in mer data automatiskt när du inkluderar instrumentationsbibliotek från OpenTelemetry-communityn.

Varning

Vi stöder inte eller garanterar inte kvaliteten på communityinstrumentationsbibliotek. Att föreslå en för vår distribution, post eller up-vote i vår feedback community. Tänk på att vissa baseras på experimentella OpenTelemetry-specifikationer och kan introducera framtida icke-bakåtkompatibla ändringar.

Om du vill lägga till ett community-bibliotek använder du ConfigureOpenTelemetryMeterProvider metoderna eller ConfigureOpenTelemetryTracerProvider när du har lagt till NuGet-paketet för biblioteket.

I följande exempel visas hur Runtime Instrumentation kan läggas till för att samla in extra mått:

dotnet add package OpenTelemetry.Instrumentation.Runtime 

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddRuntimeInstrumentation());

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Samla in anpassad telemetri

I det här avsnittet beskrivs hur du samlar in anpassad telemetri från ditt program.

Beroende på språk och signaltyp finns det olika sätt att samla in anpassad telemetri, inklusive:

  • OpenTelemetry-API
  • Språkspecifika loggnings-/måttbibliotek
  • Klassiskt API för Application Insights

Följande tabell representerar de anpassade telemetrityper som stöds för närvarande:

Språk Anpassade händelser Anpassade mått Beroenden Undantag Sidvisningar begäranden Spårningar
ASP.NET Core
   OpenTelemetry-API Ja Ja Ja Ja
   ILogger Application Programming Interface Ja
   KLASSISK API för AI
Java
   OpenTelemetry-API Ja Ja Ja Ja
   Logback, Log4j, JUL Ja Ja
   Mått för Micrometer Ja
   KLASSISK API för AI Ja Ja Ja Ja Ja Ja Ja
Node.js
   OpenTelemetry-API Ja Ja Ja Ja
Python
   OpenTelemetry-API Ja Ja Ja Ja
   Python-loggningsmodul Ja
   Händelsetillägg Ja Ja

Kommentar

Application Insights Java 3.x lyssnar efter telemetri som skickas till det klassiska API:et för Application Insights. På samma sätt samlar Application Insights Node.js 3.x in händelser som skapats med det klassiska API:et för Application Insights. Detta gör uppgraderingen enklare och fyller ett tomrum i vårt anpassade telemetristöd tills alla anpassade telemetrityper stöds via OpenTelemetry-API:et.

Lägga till anpassade mått

I det här sammanhanget refererar den anpassade måtttermen till att manuellt instrumentera koden för att samla in ytterligare mått utöver vad OpenTelemetry Instrumentation Libraries automatiskt samlar in.

OpenTelemetry-API:et erbjuder sex måttinstrument för olika måttscenarier och du måste välja rätt sammansättningstyp när du visualiserar mått i Metrics Explorer. Det här kravet gäller när du använder OPENTelemetry Metric API för att skicka mått och när du använder ett instrumentationsbibliotek.

I följande tabell visas de rekommenderade aggregeringstyperna för vart och ett av Måttinstrumenten för OpenTelemetry.

OpenTelemetry-instrument Sammansättningstyp för Azure Monitor
Räknare Sum
Asynkron räknare Sum
Histogram Min, Max, Genomsnitt, Summa och Antal
Asynkron mätare Genomsnitt
UpDownCounter Sum
Asynkron UpDownCounter Sum

Varning

Sammansättningstyper utöver vad som visas i tabellen är vanligtvis inte meningsfulla.

OpenTelemetry-specifikationen beskriver instrumenten och ger exempel på när du kan använda var och en.

Dricks

Histogrammet är det mest mångsidiga och närmaste motsvarigheten till Application Insights GetMetric Classic API. Azure Monitor plattar för närvarande ut histograminstrumentet till våra fem sammansättningstyper som stöds och stöd för percentiler pågår. Även om de är mindre mångsidiga har andra OpenTelemetry-instrument en mindre inverkan på programmets prestanda.

Histogramexempel

Programstart måste prenumerera på en mätare med namnet:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter Måste initieras med samma namn:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

Räknarexempel

Programstart måste prenumerera på en mätare med namnet:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter Måste initieras med samma namn:

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

Mätarexempel

Programstart måste prenumerera på en mätare med namnet:

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter Måste initieras med samma namn:

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));

private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID, and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
    }
}

Lägga till anpassade undantag

Välj instrumentationsbibliotek rapporterar automatiskt undantag till Application Insights. Du kanske dock vill rapportera undantag manuellt utöver vilken rapport om instrumentationsbibliotek. Till exempel rapporteras undantag som fångas av koden vanligtvis inte. Du kanske vill rapportera dem för att uppmärksamma relevanta upplevelser, inklusive avsnittet fel och transaktionsvyer från slutpunkt till slutpunkt.

  • Så här loggar du ett undantag med hjälp av en aktivitet:

    // Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • Så här loggar du ett undantag med :ILogger

    // Create a logger using the logger factory. The logger category name is used to filter and route log messages.
var logger = loggerFactory.CreateLogger(logCategoryName);

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

Lägga till anpassade intervall

Du kanske vill lägga till ett anpassat spann i två scenarier. Först när det finns en beroendebegäran som inte redan samlats in av ett instrumentationsbibliotek. För det andra, när du vill modellera en programprocess som ett spann i transaktionsvyn från slutpunkt till slutpunkt.

Kommentar

Klasserna Activity och ActivitySource från System.Diagnostics namnområdet representerar OpenTelemetry-begreppen Span för respektive Tracer. Du skapar ActivitySource direkt med konstruktorn i stället för med hjälp TracerProviderav . Varje ActivitySource klass måste uttryckligen anslutas till TracerProvider med hjälp AddSource()av . Det beror på att delar av OpenTelemetry-spårnings-API:et införlivas direkt i .NET-körningen. Mer information finns i Introduktion till OpenTelemetry .NET Tracing API.

// Define an activity source named "ActivitySourceName". This activity source will be used to create activities for all requests to the application.
internal static readonly ActivitySource activitySource = new("ActivitySourceName");

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName". This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

// Start the ASP.NET Core application.
app.Run();

StartActivity standardvärdet är ActivityKind.Internal, men du kan ange andra ActivityKind. ActivityKind.Client, ActivityKind.Produceroch ActivityKind.Internal mappas till Application Insights dependencies. ActivityKind.Server och ActivityKind.Consumer mappas till Application Insights requests.

Skicka anpassad telemetri med det klassiska API:et för Application Insights

Vi rekommenderar att du använder OpenTelemetry-API:er när det är möjligt, men det kan finnas vissa scenarier när du måste använda det klassiska API:et för Application Insights.

Händelser

  1. Lägg till Microsoft.ApplicationInsights i ditt program.

  2. Skapa en TelemetryClient instans:

    Kommentar

    Det är viktigt att bara skapa en instans av TelemetryClient per program.

    var telemetryConfiguration = new TelemetryConfiguration { ConnectionString = "" };
var telemetryClient = new TelemetryClient(telemetryConfiguration);

  3. Använd klienten för att skicka anpassad telemetri:

    telemetryClient.TrackEvent("testEvent");

Ändra telemetri

I det här avsnittet beskrivs hur du ändrar telemetri.

Lägga till span-attribut

Dessa attribut kan vara att lägga till en anpassad egenskap i telemetrin. Du kan också använda attribut för att ange valfria fält i Application Insights-schemat, till exempel klient-IP.

Lägga till en anpassad egenskap i ett spann

Alla attribut som du lägger till i intervall exporteras som anpassade egenskaper. De fyller i fältet customDimensions i tabellen begäranden, beroenden, spårningar eller undantag.

Om du vill lägga till span-attribut använder du något av följande två sätt:

Dricks

Fördelen med att använda alternativ som tillhandahålls av instrumentationsbibliotek, när de är tillgängliga, är att hela kontexten är tillgänglig. Därför kan användarna välja att lägga till eller filtrera fler attribut. Till exempel ger alternativet berika i instrumentationsbiblioteket HttpClient användarna åtkomst till Själva HttpRequestMessage och Själva HttpResponseMessage . De kan välja vad som helst från den och lagra den som ett attribut.

  1. Många instrumentationsbibliotek ger ett berikande alternativ. Vägledning finns i readme-filerna för enskilda instrumentationsbibliotek:

  2. Använd en anpassad processor:

    Dricks

    Lägg till processorn som visas här innan du lägger till Azure Monitor.

    // Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    Lägg till ActivityEnrichingProcessor.cs i projektet med följande kod:

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

Ange användarens IP-adress

Du kan fylla i fältet client_IP för begäranden genom att ange ett attribut för intervallet. Application Insights använder IP-adressen för att generera attribut för användarplatser och tar sedan bort den som standard.

Använd exemplet med anpassad egenskap, men ersätt följande kodrader i ActivityEnrichingProcessor.cs:

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IP Address>");

Ange användar-ID eller autentiserat användar-ID

Du kan fylla i fältet user_Id eller user_AuthenticatedId för begäranden med hjälp av följande vägledning. Användar-ID är en anonym användaridentifierare. Autentiserat användar-ID är en känd användaridentifierare.

Viktigt!

Läs gällande sekretesslagar innan du anger autentiserat användar-ID.

Använd exemplet med anpassad egenskap:

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<User Id>");

Lägga till loggattribut

OpenTelemetry använder . NET:s ILogger. Det går att koppla anpassade dimensioner till loggar med hjälp av en meddelandemall.

Filtrera telemetri

Du kan använda följande sätt att filtrera bort telemetri innan den lämnar programmet.

  1. Många instrumentationsbibliotek tillhandahåller ett filteralternativ. Vägledning finns i readme-filerna för enskilda instrumentationsbibliotek:

  2. Använd en anpassad processor:

    Dricks

    Lägg till processorn som visas här innan du lägger till Azure Monitor.

    // Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityFilteringProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityFilteringProcessor()));
// Configure the OpenTelemetry tracer provider to add a new source named "ActivitySourceName".
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));
// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    Lägg till ActivityFilteringProcessor.cs i projektet med följande kod:

    public class ActivityFilteringProcessor : BaseProcessor<Activity>
{
    // The OnStart method is called when an activity is started. This is the ideal place to filter activities.
    public override void OnStart(Activity activity)
    {
        // prevents all exporters from exporting internal activities
        if (activity.Kind == ActivityKind.Internal)
        {
            activity.IsAllDataRequested = false;
        }
    }
}

  3. Om en viss källa inte uttryckligen läggs till med hjälp AddSource("ActivitySourceName")av exporteras ingen av de aktiviteter som skapas med den källan.

Hämta spårnings-ID:t eller span-ID:t

Du kan hämta Trace ID och Span ID för det aktiva spannet med hjälp av följande steg.

Kommentar

Klasserna Activity och ActivitySource från System.Diagnostics namnområdet representerar OpenTelemetry-begreppen Span för respektive Tracer. Det beror på att delar av OpenTelemetry-spårnings-API:et införlivas direkt i .NET-körningen. Mer information finns i Introduktion till OpenTelemetry .NET Tracing API.

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

Nästa steg