Share via

OpenTelemetry toevoegen, wijzigen en filteren

  • Artikel

Dit artikel bevat richtlijnen voor het toevoegen, wijzigen en filteren van OpenTelemetry voor toepassingen met behulp van Azure Monitor Application Insights.

Zie het overzicht van OpenTelemetry of de veelgestelde vragen over OpenTelemetry voor meer informatie over OpenTelemetry-concepten.

Automatische gegevensverzameling

De distributies verzamelen automatisch gegevens door openTelemetry-instrumentatiebibliotheken te bundelen.

Opgenomen instrumentatiebibliotheken

Aanvragen

Afhankelijkheden

Logboekregistratie

  • ILogger

Zie Logboekregistratie in C# en .NET en codevoorbeelden voor meer informatie.ILogger

Voetnoten

  • ¹: Ondersteunt automatische rapportage van niet-verwerkte/ondeugende uitzonderingen
  • ²: Ondersteunt metrische gegevens van OpenTelemetry
  • ³: Logboekregistratie wordt standaard alleen verzameld op INFO-niveau of hoger. Zie de configuratieopties om deze instelling te wijzigen.
  • ⁴: logboekregistratie wordt standaard alleen verzameld wanneer die logboekregistratie wordt uitgevoerd op waarschuwingsniveau of hoger.

Notitie

De Azure Monitor OpenTelemetry-distributies bevatten aangepaste toewijzingen en logica om automatisch metrische gegevens van Application Insights te verzenden.

Tip

Alle metrische gegevens van OpenTelemetry, ongeacht of deze automatisch worden verzameld uit instrumentatiebibliotheken of handmatig worden verzameld uit aangepaste codering, worden momenteel beschouwd als Application Insights 'aangepaste metrische gegevens' voor factureringsdoeleinden. Meer informatie.

Een bibliotheek voor community-instrumentatie toevoegen

U kunt automatisch meer gegevens verzamelen wanneer u instrumentatiebibliotheken van de OpenTelemetry-community opneemt.

Let op

We ondersteunen of garanderen de kwaliteit van community-instrumentatiebibliotheken niet. Als u een voor ons distributieprogramma wilt voorstellen, plaatst of stemt u in onze feedbackcommunity. Houd er rekening mee dat sommige zijn gebaseerd op experimentele OpenTelemetry-specificaties en kunnen toekomstige wijzigingen veroorzaken.

Als u een communitybibliotheek wilt toevoegen, gebruikt u de ConfigureOpenTelemetryMeterProvider of ConfigureOpenTelemetryTracerProvider methoden nadat u het NuGet-pakket voor de bibliotheek hebt toegevoegd.

In het volgende voorbeeld ziet u hoe runtime-instrumentatie kan worden toegevoegd om extra metrische gegevens te verzamelen:

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

Aangepaste telemetrie verzamelen

In deze sectie wordt uitgelegd hoe u aangepaste telemetriegegevens van uw toepassing verzamelt.

Afhankelijk van uw taal en signaaltype zijn er verschillende manieren om aangepaste telemetrie te verzamelen, waaronder:

  • OpenTelemetry-API
  • Taalspecifieke bibliotheken voor logboekregistratie/metrische gegevens
  • Klassieke Application Insights-API

De volgende tabel vertegenwoordigt de momenteel ondersteunde aangepaste telemetrietypen:

Taal Aangepaste gebeurtenissen Aangepaste metrische gegevens Afhankelijkheden Uitzonderingen Paginaweergaven Verzoeken Traceringen
ASP.NET Core
   OpenTelemetry-API Ja Ja Ja Ja
   ILogger API Ja
   KLASSIEKE AI-API
Java
   OpenTelemetry-API Ja Ja Ja Ja
   Logback, Log4j, JUL Ja Ja
   Metrische gegevens van Micrometer Ja
   KLASSIEKE AI-API Ja Ja Ja Ja Ja Ja Ja
Node.js
   OpenTelemetry-API Ja Ja Ja Ja
Python
   OpenTelemetry-API Ja Ja Ja Ja
   Module voor python-logboekregistratie Ja
   Extensie voor gebeurtenissen Ja Ja

Notitie

Application Insights Java 3.x luistert naar telemetrie die wordt verzonden naar de klassieke Application Insights-API. Op dezelfde manier verzamelt Application Insights Node.js 3.x gebeurtenissen die zijn gemaakt met de klassieke Application Insights-API. Dit maakt het upgraden eenvoudiger en vult een gat in onze aangepaste telemetrieondersteuning totdat alle aangepaste telemetrietypen worden ondersteund via de OpenTelemetry-API.

Aangepaste metrische gegevens toevoegen

In deze context verwijst de term voor aangepaste metrische gegevens naar het handmatig instrumenteren van uw code om extra metrische gegevens te verzamelen dan wat de OpenTelemetry Instrumentation Libraries automatisch verzamelen.

De OpenTelemetry-API biedt zes metrische 'instrumenten' voor verschillende metrische scenario's en u moet het juiste aggregatietype kiezen bij het visualiseren van metrische gegevens in Metrics Explorer. Deze vereiste geldt wanneer u de Metrische API voor OpenTelemetry gebruikt om metrische gegevens te verzenden en wanneer u een instrumentatiebibliotheek gebruikt.

In de volgende tabel ziet u de aanbevolen aggregatietypen voor elk van de metrische instrumenten van OpenTelemetry.

OpenTelemetry Instrument Azure Monitor-aggregatietype
teller Sum
Asynchrone teller Sum
Histogram Min, Max, Average, Sum en Count
Asynchrone meter Gemiddeld
UpDownCounter Sum
Asynchrone UpDownCounter Sum

Let op

Aggregatietypen die verder gaan dan wat in de tabel wordt weergegeven, zijn doorgaans niet zinvol.

De OpenTelemetry Specification beschrijft de instrumenten en geeft voorbeelden van wanneer u deze kunt gebruiken.

Tip

Het histogram is het meest veelzijdige en meest equivalent aan de GetMetric Classic API van Application Insights. Azure Monitor maakt het histogram-instrument momenteel plat in onze vijf ondersteunde aggregatietypen en ondersteuning voor percentielen wordt momenteel uitgevoerd. Hoewel minder veelzijdig, hebben andere OpenTelemetry-instrumenten minder invloed op de prestaties van uw toepassing.

Voorbeeld van histogram

Het opstarten van de toepassing moet zich abonneren op een meter op naam:

// 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();

De Meter moet worden geïnitialiseerd met dezelfde naam:

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

Voorbeeld van teller

Het opstarten van de toepassing moet zich abonneren op een meter op naam:

// 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();

De Meter moet worden geïnitialiseerd met dezelfde naam:

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

Metervoorbeeld

Het opstarten van de toepassing moet zich abonneren op een meter op naam:

// 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();

De Meter moet worden geïnitialiseerd met dezelfde naam:

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

Aangepaste uitzonderingen toevoegen

Selecteer instrumentatiebibliotheken rapporteren automatisch uitzonderingen op Application Insights. Het is echter mogelijk dat u uitzonderingen handmatig wilt rapporteren dan wat instrumentatiebibliotheken rapporteren. Uitzonderingen die door uw code worden gevangen, worden bijvoorbeeld niet normaal gerapporteerd. U kunt ze rapporteren om de aandacht te vestigen op relevante ervaringen, waaronder de sectie fouten en end-to-end transactieweergaven.

  • Een uitzondering registreren met behulp van een activiteit:

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

  • Een uitzondering registreren met behulp van 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" });
}

Aangepaste spanten toevoegen

U kunt een aangepaste periode toevoegen in twee scenario's. Als er eerst een afhankelijkheidsaanvraag is die nog niet is verzameld door een instrumentatiebibliotheek. Ten tweede, wanneer u een toepassingsproces wilt modelleren als een periode in de end-to-end transactieweergave.

Notitie

De Activity en ActivitySource klassen van de System.Diagnostics naamruimte vertegenwoordigen de OpenTelemetry-concepten van Span respectievelijk Tracer. U maakt ActivitySource rechtstreeks met behulp van de constructor in plaats van met behulp TracerProvidervan . Elke ActivitySource klasse moet expliciet zijn verbonden met TracerProvider behulp van AddSource(). Dat komt doordat delen van de OpenTelemetry tracing-API rechtstreeks worden opgenomen in de .NET-runtime. Zie Inleiding tot OpenTelemetry .NET Tracing-API voor meer informatie.

// 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 is standaard ingesteld ActivityKind.Internalop , maar u kunt ook andere ActivityKind. ActivityKind.Client, ActivityKind.Produceren ActivityKind.Internal zijn toegewezen aan Application Insights dependencies. ActivityKind.Server en ActivityKind.Consumer zijn toegewezen aan Application Insights requests.

Aangepaste telemetrie verzenden met behulp van de klassieke Application Insights-API

U wordt aangeraden waar mogelijk de OpenTelemetry-API's te gebruiken, maar er zijn mogelijk enkele scenario's waarin u de klassieke Application Insights-API moet gebruiken.

Gebeurtenissen

  1. Voeg deze Microsoft.ApplicationInsights toe aan uw toepassing.

  2. TelemetryClient Een exemplaar maken:

    Notitie

    Het is belangrijk dat u slechts één exemplaar van de TelemetryClient per toepassing maakt.

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

  3. Gebruik de client om aangepaste telemetrie te verzenden:

    telemetryClient.TrackEvent("testEvent");

Telemetrie wijzigen

In deze sectie wordt uitgelegd hoe u telemetrie kunt wijzigen.

Spankenmerken toevoegen

Deze kenmerken kunnen bestaan uit het toevoegen van een aangepaste eigenschap aan uw telemetrie. U kunt ook kenmerken gebruiken om optionele velden in te stellen in het Application Insights-schema, zoals client-IP.

Een aangepaste eigenschap toevoegen aan een span

Alle kenmerken die u aan spans toevoegt, worden geëxporteerd als aangepaste eigenschappen. Ze vullen het veld customDimensions in de tabel met aanvragen, afhankelijkheden, traceringen of uitzonderingen.

Als u spankenmerken wilt toevoegen, gebruikt u een van de volgende twee manieren:

Tip

Het voordeel van het gebruik van opties die worden geboden door instrumentatiebibliotheken, wanneer deze beschikbaar zijn, is dat de volledige context beschikbaar is. Hierdoor kunnen gebruikers ervoor kiezen om meer kenmerken toe te voegen of te filteren. De verrijkingsoptie in de HttpClient-instrumentatiebibliotheek geeft gebruikers bijvoorbeeld toegang tot httpRequestMessage en httpResponseMessage zelf. Ze kunnen er alles uit selecteren en opslaan als een kenmerk.

  1. Veel instrumentatiebibliotheken bieden een verrijkingsoptie. Zie de leesmij-bestanden van afzonderlijke instrumentatiebibliotheken voor hulp:

  2. Een aangepaste processor gebruiken:

    Tip

    Voeg de hier weergegeven processor toe voordat u Azure Monitor toevoegt.

    // 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();

    Voeg ActivityEnrichingProcessor.cs toe aan uw project met de volgende code:

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

Het IP-adres van de gebruiker instellen

U kunt het client_IP veld voor aanvragen vullen door een kenmerk in te stellen op het bereik. Application Insights gebruikt het IP-adres om kenmerken van gebruikerslocatie te genereren en verwijdert het vervolgens standaard.

Gebruik het voorbeeld van de aangepaste eigenschap, maar vervang de volgende coderegels inActivityEnrichingProcessor.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>");

De gebruikers-id of geverifieerde gebruikers-id instellen

U kunt het veld user_Id of user_AuthenticatedId voor aanvragen vullen met behulp van de volgende richtlijnen. Gebruikers-id is een anonieme gebruikers-id. Geverifieerde gebruikers-id is een bekende gebruikers-id.

Belangrijk

Raadpleeg de toepasselijke privacywetgeving voordat u de geverifieerde gebruikers-id instelt.

Gebruik het voorbeeld van de aangepaste eigenschap:

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

Logboekkenmerken toevoegen

OpenTelemetry maakt gebruik van . NET's ILogger. Het koppelen van aangepaste dimensies aan logboeken kan worden uitgevoerd met behulp van een berichtsjabloon.

Telemetrie filteren

U kunt de volgende manieren gebruiken om telemetrie uit te filteren voordat deze uw toepassing verlaat.

  1. Veel instrumentatiebibliotheken bieden een filteroptie. Zie de leesmij-bestanden van afzonderlijke instrumentatiebibliotheken voor hulp:

  2. Een aangepaste processor gebruiken:

    Tip

    Voeg de hier weergegeven processor toe voordat u Azure Monitor toevoegt.

    // 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();

    Voeg ActivityFilteringProcessor.cs toe aan uw project met de volgende code:

    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. Als een bepaalde bron niet expliciet wordt toegevoegd met behulp AddSource("ActivitySourceName")van, worden geen van de activiteiten die zijn gemaakt met die bron geëxporteerd.

De tracerings-id of span-id ophalen

U kunt de Trace ID en Span ID van de momenteel actieve Span verkrijgen met behulp van de volgende stappen.

Notitie

De Activity en ActivitySource klassen van de System.Diagnostics naamruimte vertegenwoordigen de OpenTelemetry-concepten van Span respectievelijk Tracer. Dat komt doordat delen van de OpenTelemetry tracing-API rechtstreeks worden opgenomen in de .NET-runtime. Zie Inleiding tot OpenTelemetry .NET Tracing-API voor meer informatie.

// 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();

Volgende stappen