Freigeben über

Azure Monitor OpenTelemetry konfigurieren

Dieses Handbuch erklärt, wie Sie OpenTelemetry (OTel) in Azure Monitor Application Insights mithilfe der Azure Monitor OpenTelemetry-Distro konfigurieren. Die richtige Konfiguration stellt eine konsistente Telemetriedatensammlung in .NET-, Java-, Node.js- und Python-Anwendungen sicher, sodass eine zuverlässigere Überwachung und Diagnose ermöglicht wird.

Hinweis

Informationen zu Azure-Funktions-Apps finden Sie unter Verwenden von OpenTelemetry mit Azure-Funktionen.

Verbindungszeichenfolge

Eine Verbindungszeichenfolge in Application Insights definiert den Zielort, an den Telemetriedaten gesendet werden.

Verwenden Sie eine der folgenden drei Möglichkeiten, um die Verbindungszeichenfolge zu konfigurieren:

  • Fügen Sie UseAzureMonitor() zu Ihrer program.cs-Datei hinzu:

    var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
    options.ConnectionString = "<Your Connection String>";
});

var app = builder.Build();

app.Run();

  • Legen Sie eine Umgebungsvariable fest.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>

  • Fügen Sie den folgenden Abschnitt in Ihrer Konfigurationsdatei appsettings.json hinzu.

    {
  "AzureMonitor": {
      "ConnectionString": "<Your Connection String>"
  }
}

Hinweis

Wenn Sie die Verbindungszeichenfolge an mehreren Stellen festlegen, wird die folgende Rangfolge eingehalten:

  1. Programmcode
  2. Umgebungsvariable
  3. Konfigurationsdatei

Festlegen von Cloudrollennamen und Cloudrolleninstanz

Bei unterstützten Sprachenerkennt die OpenTelemetry-Distribution von Azure Monitor automatisch den Ressourcenkontext und stellt Standardwerte für den Cloudrollennamen und die Eigenschaften der Cloudrolleninstanz Ihrer Komponente bereit. Möglicherweise möchten Sie jedoch die Standardwerte durch für Ihr Team sinnvollere Werte überschreiben. Der Wert des Cloudrollennamens wird in der Anwendungszuordnung als Name unter einem Knoten angezeigt.

Legen Sie den Cloudrollennamen und die Cloudrolleninstanz über Ressourcenattribute fest. Der Cloudrollenname verwendet die Attribute service.namespace und service.name, obwohl er auf service.name zurückfällt, wenn service.namespace nicht festgelegt ist. Die Cloudrolleninstanz verwendet den service.instance.id-Attributwert. Informationen zu Standardattributen für Ressourcen finden Sie unter OpenTelemetry-Semantikkonventionen.

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry()
    .UseAzureMonitor()
    // Configure the ResourceBuilder to add the custom resource attributes to all signals.
    // Custom resource attributes should be added AFTER AzureMonitor to override the default ResourceDetectors.
    .ConfigureResource(resourceBuilder => resourceBuilder.AddAttributes(resourceAttributes));

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Aktivieren der Stichprobenentnahme

Es empfiehlt sich gegebenenfalls, die Stichprobenentnahme zu aktivieren, um den Umfang der Datenerfassung und somit Ihre Kosten zu reduzieren. Azure Monitor bietet eine benutzerdefinierte Stichprobenentnahme mit festem Prozentsatz, die Ereignisse mit einem Stichprobenverhältnis auffüllt, das von Application Insights in ItemCount konvertiert wird. Die Stichprobenentnahme mit fester Rate gewährleistet eine präzise Erfahrung sowie genaue Ereignisanzahlwerte. Die Stichprobenentnahme ist so konzipiert, dass Ablaufverfolgungen dienstübergreifend erhalten bleiben, und sie ist mit älteren Application Insights-SDKs (Software Development Kits) kompatibel. Weitere Informationen zu Stichproben finden Sie hier.

Hinweis

Metriken und Protokolle sind vom Sampling nicht betroffen. Wenn unerwartete Gebühren oder hohe Kosten in Application Insights angezeigt werden, kann dieser Leitfaden hilfreich sein. Es deckt häufige Ursachen wie hohes Telemetrievolumen, Datenaufnahmespitzen und falsch konfiguriertes Sampling ab. Es ist besonders hilfreich, wenn Sie Probleme im Zusammenhang mit Kostenspitzen, Telemetrievolumen, nicht funktionierendem Sampling, Datenobergrenzen, hohem Dateninput oder unerwarteter Abrechnung beheben. Informationen zu den ersten Schritten finden Sie unter "Problembehandlung bei der Erfassung von hohen Daten in Application Insights".

Vom Sampler wird eine Stichprobenrate von 0 bis einschließlich 1 erwartet. Bei einer Rate von 0,1 werden ca. 10 % Ihrer Ablaufverfolgungen gesendet.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    options.SamplingRatio = 0.1F;
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Tipp

Wenn Sie die Samplingrate mit fester Rate/Prozentsatz verwenden und nicht sicher sind, wie Sie die Samplingrate festlegen möchten, beginnen Sie bei 5 %. (0,05 Abtastverhältnis) Passen Sie die Geschwindigkeit basierend auf der Genauigkeit der Operationen an, die in den Fehler- und Leistungspanels angezeigt werden. Eine höhere Rate führt im Allgemeinen zu einer höheren Genauigkeit. Eine Stichprobenentnahme wirkt sich jedoch IMMER auf die Genauigkeit aus. Für Warnungen sollten deshalb OpenTelemetry-Metriken verwendet werden, da diese nicht von der Stichprobenentnahme betroffen sind.

Livemetriken

Livemetriken bieten ein Echtzeit-Analysedashboard für Einblicke in die Aktivität und Leistung von Anwendungen.

Wichtig

Die zusätzlichen Nutzungsbestimmungen für Microsoft Azure-Vorschauen enthalten rechtliche Bedingungen. Sie gelten für diejenigen Azure-Features, die sich in der Beta- oder Vorschauversion befinden oder aber anderweitig noch nicht zur allgemeinen Verfügbarkeit freigegeben sind.

Dieses Feature ist standardmäßig aktiviert.

Benutzer können Livemetriken beim Konfigurieren der Distribution deaktivieren.

builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
	// Disable the Live Metrics feature.
    options.EnableLiveMetrics = false;
});

Aktivieren der Microsoft Entra ID-Authentifizierung (früher Azure AD)

Es empfiehlt sich gegebenenfalls, die Microsoft Entra-Authentifizierung zu aktivieren, um eine sicherere Verbindung mit Azure herzustellen, wodurch verhindert wird, dass nicht autorisierte Telemetriedaten in Ihrem Abonnement erfasst werden.

Weitere Informationen finden Sie auf unserer dedizierten Microsoft Entra-Authentifizierungsseite, die für jede unterstützte Sprache verknüpft ist.

Informationen zum Konfigurieren der Entra ID-Authentifizierung finden Sie unter Microsoft Entra-Authentifizierung für Application Insights.

Speicher im Offline-Modus und automatische Wiederholversuche

Azure Monitor OpenTelemetry-basierte Angebote zwischenspeichern Telemetrie, wenn eine Anwendung die Verbindung zu Application Insights unterbricht und das Senden bis zu 48 Stunden lang erneut versucht. Empfehlungen zur Datenverarbeitung finden Sie unter Exportieren und Löschen privater Daten. Anwendungen mit hoher Auslastung verlieren gelegentlich Telemetriedaten aus zwei Gründen: Überschreiten der erlaubten Zeit oder Überschreiten der maximalen Dateigröße. Bei Bedarf priorisiert das Produkt aktuelle Ereignisse gegenüber alten Ereignissen.

Das Distributionspaket enthält den AzureMonitorExporter, der standardmäßig einen der folgenden Speicherorte für den Offlinespeicher verwendet (in der Reihenfolge der Vorrangs aufgeführt):

  • Fenster
    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor
  • Nicht-Windows-System
    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

Das Standardverzeichnis kann durch Festlegen von AzureMonitorOptions.StorageDirectory überschrieben werden.

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that cannot be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Wenn Sie das Feature deaktivieren möchten, legen Sie AzureMonitorOptions.DisableOfflineStorage = true fest.

Aktivieren des OTLP-Exporters

Sie sollten neben Azure Monitor Exporter auch den OTLP-Exporter (OpenTelemetry Protocol) aktivieren, um Ihre Telemetriedaten an zwei Speicherorte zu senden.

Hinweis

Der OTLP-Exporter wird nur als Beispiel gezeigt. Wir unterstützen offiziell weder den OTLP-Exporter noch irgendwelche Komponenten oder Angebote von Drittanbietern, die diesem nachgeschaltet sind.

  1. Installieren Sie in Ihrem Projekt das Paket OpenTelemetry.Exporter.OpenTelemetryProtocol.

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. Fügen Sie den folgenden Codeausschnitt hinzu. In diesem Beispiel wird davon ausgegangen, dass Sie einen OpenTelemetry-Collector mit einem laufenden OTLP-Empfänger haben. Weitere Informationen finden Sie im Beispiel zu GitHub.

    // Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Add the OpenTelemetry OTLP exporter to the application.
// This exporter will send telemetry data to an OTLP receiver, such as Prometheus
builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

OpenTelemetry-Konfigurationen

Auf die folgenden OpenTelemetry-Konfigurationen kann bei der Verwendung der OpenTelemetry-Distributionen von Azure Monitor über Umgebungsvariablen zugegriffen werden.

Umgebungsvariable Beschreibung
APPLICATIONINSIGHTS_CONNECTION_STRING Legen Sie dies auf die Verbindungszeichenfolge für Ihre Application Insights-Ressource fest.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Legen Sie dies auf true fest, um die interne Metriksammlung zu deaktivieren.
OTEL_RESOURCE_ATTRIBUTES Schlüssel-Wert-Paare, die als Ressourcenattribute verwendet werden. Weitere Informationen zu Ressourcenattributen finden Sie in der Resource SDK-Spezifikation.
OTEL_SERVICE_NAME Legt den Wert des Ressourcenattributes service.name fest. Wenn service.name auch in OTEL_RESOURCE_ATTRIBUTES bereitgestellt wird, hat OTEL_SERVICE_NAME Vorrang.

URL-Abfragezeichenfolgen redigieren

Um URL-Abfragezeichenfolgen zu maskieren, deaktivieren Sie die Abfragezeichenfolgenerfassung. Diese Einstellung wird empfohlen, wenn Sie Azure Storage mit einem SAS-Token aufrufen.

Bei Verwendung des Distributionspakets Azure.Monitor.OpenTelemetry.AspNetCore sind sowohl ASP.NET Core- als auch HttpClient-Instrumentierungsbibliotheken enthalten. Für unser Distributionspaket ist standardmäßig die Maskierung der Abfragezeichenfolgen deaktiviert.

Um dieses Verhalten zu ändern, müssen Sie eine Umgebungsvariable entweder auf true oder false festlegen.

  • ASP.NET Core-Instrumentierung: Die Maskierung von OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION-Abfragezeichenfolgen ist standardmäßig deaktiviert. Zum Aktivieren müssen Sie diese Umgebungsvariable auf false festlegen.
  • HTTPClient-Instrumentierung: Die Maskierung von OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION-Abfragezeichenfolgen ist standardmäßig deaktiviert. Zum Aktivieren müssen Sie diese Umgebungsvariable auf false festlegen.