Přidání, úprava a filtrování OpenTelemetry

  • Článek

Tento článek obsahuje pokyny k přidání, úpravě a filtrování OpenTelemetry pro aplikace využívající Službu Application Insights služby Azure Monitor.

Další informace o konceptech OpenTelemetry najdete v přehledu OpenTelemetry nebo nejčastějších dotazech k OpenTelemetry.

Automatické shromažďování dat

Distribuce automaticky shromažďují data sdružením instrumentačních knihoven OpenTelemetry.

Zahrnuté knihovny instrumentace

Žádosti

Závislosti

Protokolování

  • ILogger

Další informace o ILoggerpoužití naleznete v tématu Protokolování v jazyce C# a .NET a příklady kódu.

Poznámka pod čarou

  • ¹: Podporuje automatické hlášení neošetřených nebo nezachycených výjimek.
  • ²: Podporuje metriky OpenTelemetry
  • ³: Ve výchozím nastavení se protokolování shromažďuje pouze na úrovni INFO nebo vyšší. Pokud chcete toto nastavení změnit, podívejte se na možnosti konfigurace.
  • ⁴: Ve výchozím nastavení se protokolování shromažďuje pouze v případě, že se protokolování provádí na úrovni UPOZORNĚNÍ nebo vyšší.

Poznámka:

Distribuce OpenTelemetry služby Azure Monitor zahrnují vlastní mapování a logiku pro automatické generování standardních metrik Application Insights.

Tip

Všechny metriky OpenTelemetry, ať už se automaticky shromažďují z knihoven instrumentace nebo ručně shromažďované z vlastního kódování, se v současné době považují za vlastní metriky Application Insights pro účely fakturace. Další informace.

Přidání knihovny instrumentace komunity

Pokud zahrnete knihovny instrumentace z komunity OpenTelemetry, můžete automaticky shromažďovat další data.

Upozornění

Nepodporujeme ani nezaručujeme kvalitu komunitních instrumentačních knihoven. Pokud ho chcete navrhnout pro naši distribuci, publikujte nebo hlasujte v naší komunitě pro zpětnou vazbu. Mějte na paměti, že některé jsou založené na experimentálních specifikacích OpenTelemetry a můžou představovat budoucí zásadní změny.

Pokud chcete přidat knihovnu komunity ConfigureOpenTelemetryMeterProvider , po přidání balíčku NuGet pro knihovnu použijte tyto metody ConfigureOpenTelemetryTracerProvider .

Následující příklad ukazuje, jak lze instrumentaci modulu runtime přidat ke shromažďování dalších metrik:

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

Shromažďování vlastních telemetrických dat

Tato část vysvětluje, jak shromažďovat vlastní telemetrická data z vaší aplikace.

V závislosti na vašem jazyce a typu signálu existují různé způsoby shromažďování vlastních telemetrických dat, mezi které patří:

  • OpenTelemetry API
  • Knihovny protokolování/metrik pro konkrétní jazyk
  • Klasické rozhraní API Application Insights

Následující tabulka představuje aktuálně podporované vlastní typy telemetrie:

Jazyk Vlastní události Vlastní metriky Závislosti Výjimky Zobrazení stránek Žádosti Trasování
ASP.NET Core
   OpenTelemetry API Ano Ano Ano Yes
   ILogger Rozhraní api Ano
   Klasické rozhraní API AI
Java
   OpenTelemetry API Ano Ano Ano Yes
   Logback, Log4j, JUL Ano Yes
   Metriky v mikrometrech Ano
   Klasické rozhraní API AI Ano Ano Ano Ano Ano Ano Yes
Node.js
   OpenTelemetry API Ano Ano Ano Yes
Python
   OpenTelemetry API Ano Ano Ano Yes
   Modul protokolování Pythonu Ano
   Rozšíření událostí Ano Ano

Poznámka:

Application Insights Java 3.x naslouchá telemetrii odesílané do klasického rozhraní API Application Insights. Podobně Application Insights Node.js 3.x shromažďuje události vytvořené pomocí klasického rozhraní API Application Insights. Díky tomu je upgrade jednodušší a vyplní mezeru v naší podpoře vlastní telemetrie, dokud nebudou podporovány všechny vlastní typy telemetrie prostřednictvím rozhraní API OpenTelemetry.

Přidání vlastních metrik

V tomto kontextu termín vlastních metrik odkazuje na ruční instrumentaci kódu, aby shromáždil další metriky nad rámec toho, co knihovny Instrumentace OpenTelemetry automaticky shromažďují.

Rozhraní Api OpenTelemetry nabízí šest "nástrojů" pro pokrytí různých scénářů metrik a při vizualizaci metrik v Průzkumníku metrik musíte vybrat správný typ agregace. Tento požadavek platí při použití rozhraní API metriky OpenTelemetry k odesílání metrik a při použití knihovny instrumentace.

Následující tabulka uvádí doporučené typy agregace pro jednotlivé nástroje metriky OpenTelemetry.

OpenTelemetry Instrument Typ agregace služby Azure Monitor
Čítač Sum
Asynchronní čítač Sum
Histogram Min, Max, Average, Sum a Count
Asynchronní měřidlo Průměr
UpDownCounter Sum
Asynchronní upDownCounter Sum

Upozornění

Typy agregace nad rámec toho, co je znázorněno v tabulce, obvykle nejsou smysluplné.

Specifikace OpenTelemetry popisuje nástroje a poskytuje příklady, kdy je možné jednotlivé nástroje použít.

Tip

Histogram je nejuniverzálnější a nejpodřenější ekvivalent rozhraní API GetMetric GetMetric. Azure Monitor v současné době zploštěná instrument histogramu do pěti podporovaných typů agregace a podpora percentilů probíhá. I když méně všestranné, jiné nástroje OpenTelemetry mají menší dopad na výkon vaší aplikace.

Příklad histogramu

Spuštění aplikace se musí přihlásit k odběru měřiče podle názvu:

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

Musí Meter být inicializován pomocí stejného názvu:

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

Příklad čítače

Spuštění aplikace se musí přihlásit k odběru měřiče podle názvu:

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

Musí Meter být inicializován pomocí stejného názvu:

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

Příklad měřidla

Spuštění aplikace se musí přihlásit k odběru měřiče podle názvu:

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

Musí Meter být inicializován pomocí stejného názvu:

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

Přidání vlastních výjimek

Výběr knihoven instrumentace automaticky hlásí výjimky do Application Insights. Můžete ale chtít ručně hlásit výjimky nad rámec sestavy knihoven instrumentace. Například výjimky zachycené vaším kódem nejsou obvykle hlášeny. Můžete je chtít nahlásit, aby upoutat pozornost v relevantních prostředích, včetně části selhání a zobrazení komplexních transakcí.

  • Protokolování výjimky pomocí aktivity:

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

  • Protokolování výjimky pomocí 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" });
}

Přidání vlastních rozsahů

Vlastní rozsah můžete přidat ve dvou scénářích. Za prvé, pokud už knihovna instrumentace neshromažďuje požadavek na závislost. Za druhé, pokud chcete modelovat proces aplikace jako rozsah v zobrazení komplexní transakce.

Poznámka:

Třídy Activity a ActivitySource z System.Diagnostics oboru názvů představují koncepty Span OpenTelemetry a Tracer, v uvedeném pořadí. Vytváříte ActivitySource přímo pomocí jeho konstruktoru místo pomocí .TracerProvider Každá ActivitySource třída musí být explicitně připojena TracerProvider pomocí .AddSource() Je to proto, že části rozhraní API trasování OpenTelemetry jsou začleněny přímo do modulu runtime .NET. Další informace najdete v tématu Úvod k rozhraní API pro trasování .NET OpenTelemetry.

// 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 výchozí hodnota ActivityKind.Internalje , ale můžete poskytnout jakékoli jiné ActivityKind. ActivityKind.Client, ActivityKind.Producera ActivityKind.Internal jsou mapovány na Application Insights dependencies. ActivityKind.Server a ActivityKind.Consumer jsou mapovány na Application Insights requests.

Odesílání vlastní telemetrie pomocí klasického rozhraní API Application Insights

Kdykoli je to možné, doporučujeme používat rozhraní API OpenTelemetry, ale v některých situacích může být nutné použít klasické rozhraní API Služby Application Insights.

Události

  1. Přidejte Microsoft.ApplicationInsights do aplikace.

  2. Vytvoření TelemetryClient instance:

    Poznámka:

    Je důležité vytvořit pouze jednu instanci TelemetryClient pro každou aplikaci.

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

  3. Pomocí klienta odešlete vlastní telemetrii:

    telemetryClient.TrackEvent("testEvent");

Úprava telemetrie

Tato část vysvětluje, jak upravit telemetrii.

Přidání atributů span

Mezi tyto atributy může patřit přidání vlastní vlastnosti do telemetrie. Pomocí atributů můžete také nastavit volitelná pole ve schématu Application Insights, jako je IP adresa klienta.

Přidání vlastní vlastnosti do spanu

Všechny atributy , které přidáte do rozsahů, se exportují jako vlastní vlastnosti. Naplní pole customDimensions v tabulce požadavků, závislostí, trasování nebo výjimek.

Pokud chcete přidat atributy span, použijte jeden z následujících dvou způsobů:

  • Použijte možnosti poskytované knihovnami instrumentace.
  • Přidání vlastního procesoru span

Tip

Výhodou použití možností poskytovaných knihovnami instrumentace, pokud jsou k dispozici, je, že je k dispozici celý kontext. V důsledku toho mohou uživatelé vybrat přidání nebo filtrování dalších atributů. Například možnost rozšiřování v knihovně instrumentace HttpClient poskytuje uživatelům přístup k HttpRequestMessage a samotné httpResponseMessage . Můžou z něj vybrat cokoli a uložit ho jako atribut.

  1. Mnoho knihoven instrumentace nabízí možnost obohacení. Pokyny najdete v souborech readme jednotlivých knihoven instrumentace:

  2. Použití vlastního procesoru:

    Tip

    Před přidáním služby Azure Monitor přidejte procesor uvedený tady.

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

    Do projektu přidejte ActivityEnrichingProcessor.cs následující kód:

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

Nastavení IP adresy uživatele

Pole client_IP pro žádosti můžete naplnit nastavením atributu v rozsahu. Application Insights používá IP adresu k vygenerování atributů umístění uživatele a ve výchozím nastavení ji zahodí.

Použijte příklad vlastní vlastnosti, ale nahraďte následující řádky kódu vActivityEnrichingProcessor.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>");

Nastavení ID uživatele nebo ověřeného ID uživatele

Pole user_Id nebo user_AuthenticatedId pro žádosti můžete naplnit pomocí následujících doprovodných materiálů. ID uživatele je anonymní identifikátor uživatele. Ověřené ID uživatele je známý identifikátor uživatele.

Důležité

Než nastavíte ID ověřeného uživatele, obraťte se na příslušné zákony o ochraně osobních údajů.

Použijte příklad vlastní vlastnosti:

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

Přidání atributů protokolu

OpenTelemetry používá . ILoggerNET . Připojení vlastních dimenzí k protokolům lze provést pomocí šablony zprávy.

Filtrování telemetrie

Před opuštěním aplikace můžete telemetrii vyfiltrovat pomocí následujících způsobů.

  1. Mnoho knihoven instrumentace poskytuje možnost filtru. Pokyny najdete v souborech readme jednotlivých knihoven instrumentace:

  2. Použití vlastního procesoru:

    Tip

    Před přidáním služby Azure Monitor přidejte procesor uvedený tady.

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

    Do projektu přidejte ActivityFilteringProcessor.cs následující kód:

    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. Pokud konkrétní zdroj není explicitně přidán pomocí , AddSource("ActivitySourceName")žádná z aktivit vytvořených pomocí tohoto zdroje se exportuje.

Získání ID trasování nebo ID rozsahu

Aktuálně aktivní span můžete získat Trace ID Span ID pomocí následujícího postupu.

Poznámka:

Třídy Activity a ActivitySource z System.Diagnostics oboru názvů představují koncepty Span OpenTelemetry a Tracer, v uvedeném pořadí. Je to proto, že části rozhraní API trasování OpenTelemetry jsou začleněny přímo do modulu runtime .NET. Další informace najdete v tématu Úvod k rozhraní API pro trasování .NET OpenTelemetry.

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

Další kroky

  • Další konfiguraci distribuce OpenTelemetry najdete v tématu Konfigurace OpenTelemetry služby Azure Monitor.
  • Informace o zdrojovém kódu najdete v úložišti Azure Monitor AspNetCore na GitHubu.
  • Pokud chcete nainstalovat balíček NuGet, vyhledat aktualizace nebo zobrazit poznámky k verzi, podívejte se na stránku balíčku NuGet AspNetCore služby Azure Monitor.
  • Pokud se chcete seznámit se službou Azure Monitor a OpenTelemetry, podívejte se na ukázkovou aplikaci Azure Monitoru.
  • Další informace o OpenTelemetry a její komunitě najdete v úložišti OpenTelemetry .NET Na GitHubu.
  • Pokud chcete povolit používání, povolte monitorování uživatelů ve webovém nebo prohlížeči.
  • Pokud chcete zkontrolovat nejčastější dotazy, postup řešení potíží, možnosti podpory nebo poskytnout zpětnou vazbu k OpenTelemetry, přečtěte si nápovědu k OpenTelemetry, podporu a zpětnou vazbu pro Azure Monitor Application Insights.