Freigeben über

Hinzufügen, Ändern und Filtern von OpenTelemetry

  • Artikel

Dieser Artikel enthält Anleitungen zum Hinzufügen, Ändern und Filtern von OpenTelemetry für Anwendungen mithilfe von Azure Monitor Application Insights.

Weitere Informationen zu OpenTelemetry-Konzepten finden Sie in der OpenTelemetry-Übersicht oder in den Häufig gestellten Fragen zu OpenTelemetry.

Automatische Datensammlung

Die Distributionen sammeln Daten automatisch durch Bündelung von OpenTelemetry-Instrumentierungsbibliotheken.

Enthaltene Instrumentierungsbibliotheken

Anforderungen

Abhängigkeiten

Logging

  • ILogger

Weitere Informationen zu ILogger finden Sie unter Protokollierung in C# und .NET und unter Codebeispiele.

Fußnoten

  • ¹: Unterstützt das automatische Melden von unbehandelten/nicht erkannten Fehlern
  • ²: Unterstützt OpenTelemetry-Metriken
  • ³: Die Protokollierung erfolgt standardmäßig mindestens auf INFO-Ebene. Um diese Einstellung zu ändern, lesen Sie die Konfigurationsoptionen.
  • ⁴: Die Protokollierung wird standardmäßig nur erfasst, wenn sie auf der Ebene WARNUNG oder höher erfolgt.

Hinweis

Die OpenTelemetry-Distributionen von Azure Monitor umfassen eine benutzerdefinierte Zuordnung und Logik, um automatisch Application Insights-Standardmetriken auszugeben.

Tipp

Alle OpenTelemetry-Metriken, unabhängig davon, ob sie automatisch von Instrumentenbibliotheken oder manuell durch benutzerdefinierte Codierung erfasst werden, gelten derzeit für Abrechnungszwecke als „benutzerdefinierte Metriken“ von Application Insights. Weitere Informationen

Hinzufügen einer Community-Instrumentierungsbibliothek

Sie können automatisch mehr Daten sammeln, wenn Sie Instrumentierungsbibliotheken aus der OpenTelemetry-Community einschließen.

Achtung

Community-Instrumentierungsbibliotheken werden von uns nicht unterstützt und wir übernehmen keine Garantie für ihre Qualität. Wenn Sie einen Vorschlag für unsere Distribution machen möchten, posten Sie ihn in unserer Feedback-Community oder geben Sie dort ein Up-Vote ab. Beachten Sie, dass einige auf experimentellen OpenTelemetry-Spezifikationen basieren und möglicherweise zukünftige grundlegende Änderungen einführen.

Verwenden Sie zum Hinzufügen einer Communitybibliothek die Methoden ConfigureOpenTelemetryMeterProvider oder ConfigureOpenTelemetryTracerProvider, nachdem Sie das NuGet-Paket für die Bibliothek hinzugefügt haben.

Im folgenden Beispiel wird veranschaulicht, wie die Laufzeitinstrumentierung hinzugefügt werden kann, um zusätzliche Metriken zu sammeln:

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

Erfassen benutzerdefinierter Telemetriedaten

In diesem Abschnitt erfahren Sie, wie Sie benutzerdefinierte Telemetrie aus Ihrer Anwendung erfassen.

Abhängig von Ihrer Sprache und Ihrem Signaltyp gibt es verschiedene Möglichkeiten, benutzerdefinierte Telemetriedaten zu erfassen, darunter:

  • OpenTelemetry-API
  • Sprachspezifische Protokollierung/Metrikbibliotheken
  • Classic API von Application Insights

Die folgende Tabelle stellt die derzeit unterstützten benutzerdefinierten Telemetrietypen dar:

Sprache Benutzerdefinierte Ereignisse Benutzerdefinierte Metriken Abhängigkeiten Ausnahmen Seitenaufrufe Requests Traces
ASP.NET Core
   OpenTelemetry-API Ja Ja Ja Ja
   ILogger API Ja
   KI Classic API
Java
   OpenTelemetry-API Ja Ja Ja Ja
   Logback, Log4j, JUL Ja Ja
   Mikrometer-Metriken Ja
   KI Classic API Ja Ja Ja Ja Ja Ja Ja
Node.js
   OpenTelemetry-API Ja Ja Ja Ja
Python
   OpenTelemetry-API Ja Ja Ja Ja
   Python-Protokollierungsmodul Ja
   Ereigniserweiterung Ja Ja

Hinweis

Application Insights Java 3.x lauscht auf Telemetriedaten, die an die Classic API von Application Insights gesendet werden. Auf ähnliche Weise erfasst Application Insights Node.js 3.x Ereignisse, die mit der Classic API von Application Insights erstellt wurden. Dies erleichtert Upgrades und füllt eine Lücke in unserer Unterstützung für benutzerdefinierte Telemetrie, bis alle benutzerdefinierten Telemetrietypen über die OpenTelemetry-API unterstützt werden.

Hinzufügen benutzerdefinierter Metriken

In diesem Zusammenhang bezieht sich der Begriff „benutzerdefinierte Metriken” darauf, Ihren Code manuell zu instrumentieren, um zusätzliche Metriken zu sammeln, die über das hinausgehen, was die OpenTelemetry Instrumentierungsbibliotheken automatisch sammeln.

Die OpenTelemetry-API bietet sechs Metrikinstrumente zur Abdeckung verschiedener Metrikszenarien, und Sie müssen beim Visualisieren von Metriken im Metrik-Explorer den richtigen Aggregationstyp auswählen. Diese Anforderung gilt bei Verwendung der OpenTelemetry-Metrik-API zum Senden von Metriken sowie bei Verwendung einer Instrumentierungsbibliothek.

Die folgende Tabelle enthält die empfohlenen Aggregationstypen für die einzelnen OpenTelemetry-Metrikinstrumente:

OpenTelemetry-Instrument Aggregationstyp von Azure Monitor
Leistungsindikator Sum
Asynchroner Zähler Sum
Histogramm Minimum, Maximum, Mittelwert, Summe und Anzahl
Asynchrones Messgerät Average
UpDownCounter Sum
UpDownCounter (asynchron) Sum

Achtung

Andere Aggregationstypen als die in der Tabelle angegebenen Typen sind in der Regel nicht aussagekräftig.

Die OpenTelemetry-Spezifikation beschreibt die Instrumente und enthält Verwendungsbeispiele.

Tipp

Das Histogramm ist am vielseitigsten und entspricht am ehesten der Classic API von Application Insights für GetMetric. Azure Monitor vereinfacht das Histogramminstrument derzeit mit unseren fünf unterstützten Aggregationstypen, und Quantile werden demnächst unterstützt. Andere OpenTelemetry-Instrumente sind zwar weniger vielseitig, haben dafür aber auch weniger Auswirkungen auf die Leistung Ihrer Anwendung.

Histogrammbeispiel

Der Anwendungsstart muss eine Verbrauchseinheit nach Name abonnieren:

// 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 muss mit demselben Namen initialisiert werden:

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

Counter-Beispiel

Der Anwendungsstart muss eine Verbrauchseinheit nach Name abonnieren:

// 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 muss mit demselben Namen initialisiert werden:

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

Messgerätbeispiel

Der Anwendungsstart muss eine Verbrauchseinheit nach Name abonnieren:

// 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 muss mit demselben Namen initialisiert werden:

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

Hinzufügen benutzerdefinierter Ausnahmen

Bestimmte Instrumentierungsbibliotheken melden automatisch Ausnahmen für Application Insights. Möglicherweise möchten Sie jedoch manuell Ausnahmen melden, die über die Berichte von Instrumentierungsbibliotheken hinausgehen. Beispielsweise werden von Ihrem Code erfasste Ausnahmen üblicherweise nicht gemeldet. Unter Umständen empfiehlt es sich, sie zu melden, um in relevanten Umgebungen auf sie aufmerksam zu machen. Hierzu zählen unter anderem der Fehlerabschnitt sowie End-to-End-Transaktionsansichten.

  • Protokollieren einer Ausnahme mithilfe einer Aktivität:

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

  • Protokollieren einer Ausnahme mithilfe von 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" });
}

Hinzufügen von benutzerdefinierten Spannen

In zwei Szenarien sollten Sie eine benutzerdefinierte Spanne hinzufügen. Erstens, wenn eine Abhängigkeitsanforderung vorhanden ist, die nicht bereits von einer Instrumentierungsbibliothek erfasst wurde. Zweitens, wenn Sie einen Anwendungsprozess als Spanne in der End-to-End-Transaktionsansicht modellieren möchten.

Hinweis

Die Klassen Activity und ActivitySource aus dem System.Diagnostics-Namespace stellen die OpenTelemetry-Konzepte von Span bzw. Tracer dar. Sie erstellen ActivitySource direkt mithilfe des Konstruktors anstelle von mithilfe von TracerProvider. Jede Klasse ActivitySource muss mithilfe von AddSource() explizit mit TracerProvider verbunden werden. Dies liegt daran, dass Teile der OpenTelemetry-Ablaufverfolgungs-API direkt in die .NET-Runtime integriert sind. Weitere Informationen finden Sie unter Einführung in die .NET-Ablaufverfolgungs-API für 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 ist standardmäßig auf ActivityKind.Internal festgelegt. Sie können jedoch eine beliebige andere ActivityKind angeben. ActivityKind.Client, ActivityKind.Producer und ActivityKind.Internal sind Application Insights-dependencies zugeordnet. ActivityKind.Server und ActivityKind.Consumer sind Application Insights-requests zugeordnet.

Senden von benutzerdefinierten Telemetriedaten mithilfe der Classic API von Application Insights

Es wird empfohlen, nach Möglichkeit die OpenTelemetry-APIs zu verwenden. Es kann jedoch einige Szenarien geben, in denen Sie die Classic API von Application Insights verwenden müssen.

Ereignisse

  1. Fügen Sie Ihrer Anwendung Microsoft.ApplicationInsights hinzu.

  2. Erstellen Sie eine TelemetryClient-Instanz:

    Hinweis

    Es ist wichtig, nur einmal eine Instanz des TelemetryClient pro Anwendung zu erstellen.

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

  3. Verwenden Sie den Client, um benutzerdefinierte Telemetriedaten zu senden:

    telemetryClient.TrackEvent("testEvent");

Ändern der Telemetrie

In diesem Abschnitt wird das Ändern von Telemetriedaten erläutert.

Hinzufügen von span-Attributen

Zu diesen Attributen kann das Hinzufügen einer benutzerdefinierten Eigenschaft zu Ihrer Telemetrie gehören. Sie können auch Attribute verwenden, um optionale Felder im Application Insights-Schema festzulegen, z. B. Client-IP.

Hinzufügen einer benutzerdefinierten Eigenschaft zu einer Spanne

Alle Attribute, die Sie Spans hinzufügen, werden als benutzerdefinierte Eigenschaften exportiert. Sie füllen das Feld customDimensions in der Tabelle mit Anforderungen, Abhängigkeiten, Überwachungen oder Ausnahmen mit Daten auf.

Verwenden Sie zum Hinzufügen von Span-Attributen eine der beiden folgenden Möglichkeiten:

Tipp

Der Vorteil der Verwendung von Optionen, die von Instrumentierungsbibliotheken bereitgestellt werden, wenn sie verfügbar sind, ist, dass der gesamte Kontext verfügbar ist. Dadurch können Benutzer weitere Attribute hinzufügen oder filtern. Mit der Option „anreichern“ in der HttpClient-Instrumentierungsbibliothek erhalten Benutzer beispielsweise Zugriff auf HttpRequestMessage und die HttpResponseMessage selbst. Sie können alles daraus auswählen und als Attribut speichern.

  1. Viele Instrumentierungsbibliotheken bieten eine Anreicherungsoption. Eine Anleitung finden Sie in den Readme-Dateien der einzelnen Instrumentierungsbibliotheken:

  2. Verwenden eines benutzerdefinierten Prozessors:

    Tipp

    Fügen Sie den hier gezeigten Prozessor vor dem Hinzufügen von Azure Monitor hinzu.

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

    Fügen Sie Ihrem Projekt ActivityEnrichingProcessor.cs mit dem unten aufgeführten Code hinzu:

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

Festlegen der Benutzer-IP

Sie können das Feld client_IP für Anforderungen auffüllen, indem Sie ein Attribut für den Bereich festlegen. Application Insights verwendet die IP-Adresse zum Generieren von Benutzerstandortattributen und verwirft sie dann standardmäßig.

Verwenden Sie das Beispiel einer benutzerdefinierten Eigenschaft, ersetzen Sie dabei aber die folgenden Codezeilen 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>");

Festlegen der Benutzer-ID oder der authentifizierten Benutzer-ID

Sie können das Feld user_Id oder user_AuthenticatedId für Anforderungen mit Daten auffüllen, indem Sie die folgende Anleitung verwenden. Die Benutzer-ID ist ein anonymer Benutzerbezeichner. Die authentifizierte Benutzer-ID ist ein bekannter Benutzerbezeichner.

Wichtig

Informieren Sie sich über die geltenden Datenschutzgesetze, bevor Sie die authentifizierte Benutzer-ID festlegen.

Verwenden Sie das Beispiel einer benutzerdefinierten Eigenschaft:

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

Hinzufügen von Protokollattributen

OpenTelemetry verwendet den ILogger von .NET. Das Anfügen benutzerdefinierter Dimensionen an Protokolle kann mithilfe einer Nachrichtenvorlage erfolgen.

Filtern von Telemetriedaten

Sie können die folgenden Methoden verwenden, um Telemetriedaten herausfiltern, bevor sie Ihre Anwendung verlassen.

  1. Viele Instrumentierungsbibliotheken bieten eine Filteroption. Eine Anleitung finden Sie in den Readme-Dateien der einzelnen Instrumentierungsbibliotheken:

  2. Verwenden eines benutzerdefinierten Prozessors:

    Tipp

    Fügen Sie den hier gezeigten Prozessor vor dem Hinzufügen von Azure Monitor hinzu.

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

    Fügen Sie Ihrem Projekt ActivityFilteringProcessor.cs mit dem unten aufgeführten Code hinzu:

    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. Wenn eine bestimmte Quelle nicht explizit mit AddSource("ActivitySourceName") hinzugefügt wird, wird keine der Aktivitäten exportiert, die mit dieser Quelle erstellt wurden.

Abrufen der Ablaufverfolgungs-ID oder Span-ID

Sie können mit den folgenden Schritten die Trace ID und Span ID der derzeit aktiven Span abrufen.

Hinweis

Die Klassen Activity und ActivitySource aus dem System.Diagnostics-Namespace stellen die OpenTelemetry-Konzepte von Span bzw. Tracer dar. Dies liegt daran, dass Teile der OpenTelemetry-Ablaufverfolgungs-API direkt in die .NET-Runtime integriert sind. Weitere Informationen finden Sie unter Einführung in die .NET-Ablaufverfolgungs-API für 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();

Nächste Schritte