Dela via

Lägga till och ändra Azure Monitor OpenTelemetry för .NET-, Java-, Node.js- och Python-program

Den här guiden innehåller instruktioner om hur du integrerar och anpassar OTel-instrumentation (OpenTelemetry) i Azure Monitor Application Insights.

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

Kommentar

Information om Azure Function Apps finns i Använda OpenTelemetry med Azure Functions.

Automatisk datainsamling

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

Inkluderade instrumentationsbibliotek

Förfrågningar

Beroenden

Loggning

  • ILogger

Om du vill minska eller öka antalet loggar som skickas till Azure Monitor konfigurerar du loggning för att ange lämplig loggnivå eller tillämpa filter. Du kan till exempel välja att skicka endast Warning och Error loggar till OpenTelemetry/Azure Monitor. OpenTelemetry styr inte loggroutning eller filtrering – din ILogger-konfiguration fattar dessa beslut. Mer information om hur du konfigurerar ILoggerfinns i Konfigurera loggning.

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

Fotnoter

  • ¹: Stöder automatisk rapportering av ohanterade/ofångade undantag
  • ²: Stöder OpenTelemetry-mått

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. För att föreslå en för vår distribution, publicera eller rösta upp i vår återkopplingsgemenskap. 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();

Resursdetektorer

Resursdetektorer identifierar miljömetadata vid start och fyller i OpenTelemetry-resursattribut som service.name, cloud.provideroch cloud.resource_id. Dessa metadata driver upplevelser i Application Insights som programkarta och beräkningslänkning, och det förbättrar korrelationen mellan spårningar, mått och loggar.

Dricks

Resursattribut beskriver processen och dess miljö. Span-attribut beskriver en enda åtgärd. Använd resursattribut för appnivåegenskaper som service.name.

Miljötyper som stöds

Miljö Så här fungerar identifiering Noteringar
Azure App Service Språk-SDK eller Azure Monitor-distribution läser välkända App Service-miljövariabler och värdmetadata Fungerar med .NET, Java, Node.jsoch Python när du använder vägledningen i den här artikeln.
Azure-funktioner Se instruktioner för Azure Functions OpenTelemetry Alla Azure Functions-riktlinjer finns där.
Virtuella maskiner i Azure Språk-SDK eller distribution frågar Azure Instance Metadata Service Kontrollera att den virtuella datorn har åtkomst till slutpunkten för instansmetadatatjänsten.
Azure Kubernetes Service (AKS) Använda OpenTelemetry Collector-processorn k8sattributes för att lägga till Kubernetes-metadata Rekommenderas för alla programmeringsspråk som körs i AKS.
Azure Container-applikationer Detektorer mappar miljövariabler och resursidentifierare när de är tillgängliga Du kan också ange OTEL_RESOURCE_ATTRIBUTES för att fylla luckor.

Manuell och automatisk instrumentering

  • Automatisk instrumentering och Azure Monitor-distributioner aktiverar resursidentifiering när de körs i Azure-miljöer där det stöds.

  • För manuella installationer kan du ange resursattribut direkt med standardalternativ för OpenTelemetry:

    # Applies to .NET (ASP.NET/ASP.NET Core), Java, Node.js, and Python
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

    I Windows PowerShell:

    $Env:OTEL_SERVICE_NAME="my-service"
$Env:OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

Överväganden för OTLP-inmatning

  • Application Insights använder service.name för att härleda molnrollnamn. Välj ett stabilt namn per tjänst för att undvika fragmenterade noder i programkartan.
  • cloud.resource_id förbättrar beräkningslänkningen till Azure-resurser. Om det här attributet saknas, kanske vissa upplevelser inte kommer att visa den Azure-resurs som producerade data.

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 och Application Insights Node.js 3.x samlar in telemetri från det klassiska API:et för Application Insights. Det här beteendet förenklar uppgraderingar och stöder tillfälligt anpassad telemetri tills OpenTelemetry-API:et innehåller alla anpassade telemetrityper.

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 extra mått utöver vad OpenTelemetry Instrumentation Libraries automatiskt samlar in. Mer information om hur du använder mått finns i Mått i Application Insights.

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 Summa
Asynkron räknare Summa
Histogram Min, Max, Genomsnitt, Summa och Antal
Asynkron mätare Genomsnitt
Upp-och-ner-räknare Summa
Asynkron UpDownCounter Summa

Varning

Andra sammansättningstyper är i de flesta fall 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 effekt 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 anpassade händelser

Application Insights lagrar anpassade händelser i customEvents tabellen. Ett sätt att analysera, filtrera och visualisera dem är att använda Application Insights-användningsupplevelserna.

Om du vill automatisera samlingen av interaktionshändelser på klientsidan kan du använda plugin-programmet i JavaScript SDK.

Anpassade händelser är i offentlig förhandsgranskning och använder Azure.Monitor.OpenTelemetry.AspNetCore 1.3.0-beta.3.

Viktigt!

Se kompletterande användningsvillkor för Förhandsversioner av Microsoft Azure för juridiska villkor som gäller för Azure-funktioner som är i betaversion, förhandsversion eller på annat sätt ännu inte har släppts i allmän tillgänglighet.

För att skicka en CustomEvent med hjälp av ILogger, ange "microsoft.custom_event.name"-attributet i meddelandemallen.

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

Ä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. Alternativet att berika i instrumentationsbiblioteket HttpClient ger användarna åtkomst till HttpRequestMessage och 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.

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