Delen via

Azure Monitor OpenTelemetry toevoegen en wijzigen voor .NET-, Java-, Node.js- en Python-toepassingen

Deze handleiding bevat instructies voor het integreren en aanpassen van OTelemetry-instrumentatie (OpenTelemetry) in Azure Monitor Application Insights.

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

Notitie

Zie OpenTelemetry gebruiken met Azure Functions voor Azure Function-apps.

Automatische gegevensverzameling

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

Opgenomen instrumentatiebibliotheken

Verzoeken

Afhankelijkheden

Logboekregistratie

  • ILogger

Als u het aantal logboeken dat naar Azure Monitor wordt verzonden wilt verminderen of verhogen, configureert u logboekregistratie om het juiste logboekniveau in te stellen of filters toe te passen. U kunt er bijvoorbeeld voor kiezen om alleen Warning- en Error-logs naar OpenTelemetry/Azure Monitor te verzenden. OpenTelemetry beheert geen logboekroutering of -filtering. Uw ILogger configuratie neemt deze beslissingen. Voor meer informatie over het configureren van ILogger, zie Logboekregistratie configureren.

Zie ILogger en codevoorbeelden voor meer informatie.

Voetnoten

  • ¹: Ondersteunt automatische rapportage van niet-verwerkte/niet-opgevangen uitzonderingen
  • ²: Ondersteunt metrische gegevens van OpenTelemetry

Notitie

De Azure Monitor OpenTelemetry Distributies bevatten aangepaste toewijzingen en logica om automatisch metrische gegevens van Application Insights uit te zenden.

Aanbeveling

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. Om er een voor onze distributie voor te stellen, plaats een bericht of stem voor 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 en Application Insights Node.js 3.x verzamelen telemetrie van de klassieke Application Insights-API. Dit gedrag vereenvoudigt upgrades en ondersteunt tijdelijk aangepaste telemetrie totdat de OpenTelemetry-API alle aangepaste telemetrietypen bevat.

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 buiten wat de OpenTelemetry Instrumentation-bibliotheken 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 Som
Asynchrone teller Som
Histogram Min, Max, Average, Sum en Count
Asynchrone meter Gemiddeld
UpDownCounter Som
Asynchrone UpDownCounter Som

Let op

Andere aggregatietypen zijn in de meeste gevallen niet zinvol.

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

Aanbeveling

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 een minder effect 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(). Dit komt doordat delen van de OpenTelemetry tracing-API rechtstreeks zijn 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 gebeurtenissen verzenden

Application Insights slaat aangepaste gebeurtenissen op in de customEvents tabel. Een manier om ze te analyseren, filteren en visualiseren , is door gebruik te maken van de Application Insights-gebruikservaringen.

Als u de verzameling interactiegebeurtenissen aan de clientzijde wilt automatiseren, kunt u de invoegtoepassing gebruiken in de JavaScript SDK.

Aangepaste gebeurtenissen bevinden zich in openbare preview en gebruiken Azure.Monitor.OpenTelemetry.AspNetCore 1.3.0-beta.3.

Belangrijk

Zie de aanvullende gebruiksvoorwaarden voor Microsoft Azure Previews voor juridische voorwaarden die van toepassing zijn op Azure-functies die bèta, preview of anderszins nog niet zijn uitgebracht in algemene beschikbaarheid.

Om een CustomEvent te verzenden met behulp van ILogger, stelt u het "microsoft.custom_event.name" kenmerk in de berichtsjabloon in.

// Create a logger factory and configure OpenTelemetry with Azure Monitor
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddOpenTelemetry(options =>
        {
            options.AddAzureMonitorLogExporter();
        });
});

// Create a logger for the specified category
var logger = loggerFactory.CreateLogger(logCategoryName);

// Log a custom event with a custom name and additional attribute
// The 'microsoft.custom_event.name' value will be used as the name of the customEvent
logger.LogInformation("{microsoft.custom_event.name} {additional_attrs}", "test-event-name", "val1");

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:

Aanbeveling

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 httpResponseMessagezelf. 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:

    Aanbeveling

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

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.

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. Dit komt doordat delen van de OpenTelemetry tracing-API rechtstreeks zijn 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