Azure Monitor OpenTelemetry konfigurieren

  • Artikel

In diesem Artikel werden Konfigurationseinstellungen für die OpenTelemetry-Distribution von Azure Monitor behandelt.

Connection string

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 der Datei program.cs UseAzureMonitor() 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. Code
  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(_testResourceAttributes));

// 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.

Von der Stichprobenentnahme wird eine Stichprobenrate zwischen 0 und 1 (einschließlich) erwartet. Bei einer Rate von 0,1 werden ca. zehn Prozent 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 Stichproben mit einer festen Rate bzw. Prozentsatzstichproben verwenden und nicht sicher sind, auf welchen Wert Sie die Stichprobenrate festlegen sollen, beginnen Sie mit fünf Prozent (entspricht einem Stichprobenverhältnis von 0,05), und passen Sie die Rate basierend auf der Genauigkeit der Vorgänge an, die auf den Bereichen zu Fehlern und zur Leistung 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.

Wir unterstützen die von Azure Identity bereitgestellten Anmeldeinformationsklassen.

  • Wir empfehlen DefaultAzureCredential für die lokale Entwicklung.
  • Wir empfehlen ManagedIdentityCredential wird für systemseitig zugewiesene und benutzerseitig zugewiesene verwaltete Identitäten.
    • Verwenden Sie bei systemseitig zugewiesenen Identitäten den Standardkonstruktor ohne Parameter.
    • Stellen Sie bei benutzerseitig zugewiesenen Identitäten die Client-ID für den Konstruktor bereit.
  • Wir empfehlen ClientSecretCredential für Dienstprinzipale.
    • Geben Sie die Mandanten-ID, die Client-ID und den geheimen Clientschlüssel für den Konstruktor an.

  1. Installieren Sie das neueste Azure.Identity-Paket:

    dotnet add package Azure.Identity

  2. Geben Sie die gewünschte Klasse für Anmeldeinformation an:

    // 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 credential to the DefaultAzureCredential.
    // This credential will use the Azure identity of the current user or
    // the service principal that the application is running as to authenticate
    // to Azure Monitor.
    options.Credential = new DefaultAzureCredential();
});

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

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

Offlinespeicher und automatische Wiederholungen

Um die Zuverlässigkeit und Resilienz zu verbessern, schreiben auf Azure Monitor OpenTelemetry basierende Angebote standardmäßig in Offlinespeicher bzw. in lokalen Speicher, wenn die Application Insights-Verbindung einer Anwendung unterbrochen wird. Anwendungstelemetriedaten werden auf dem Datenträger gespeichert, und es wird regelmäßig bis zu 48 Stunden lang erneut versucht, die Daten zu senden. In Anwendungen mit hoher Auslastung wird Telemetrie gelegentlich aus zwei Gründen gelöscht. Entweder beim Überschreiten der zulässigen Zeit oder beim Überschreiten der maximalen Dateigröße oder wenn das SDK keine Möglichkeit hat, die Datei zu bereinigen. Falls erforderlich, werden alte Ereignisse mit neueren Ereignissen überschrieben. Weitere Informationen

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):

  • Windows
    • %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 über einen OpenTelemetry-Collector mit einem aktuell ausgeführten OTLP-Empfänger verfügen. 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 maskieren

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.