Untersuchen von .NET/.NET Core- und Python-Ablaufverfolgungsprotokollen in Application Insights

Senden Sie Protokolle für die Diagnoseablaufverfolgung für Ihre ASP.NET/ASP.NET Core-Anwendung von ILogger, NLog, log4Net oder System.Diagnostics.Trace an Azure Application Insights. Für Python-Anwendungen senden Sie Protokolle für die Diagnoseablaufverfolgung mithilfe von AzureLogHandler in OpenCensus Python für Azure Monitor. Sie können Sie anschließend untersuchen und nach ihnen suchen. Diese Protokolle werden mit den anderen Protokolldateien Ihrer Anwendung zusammengeführt, sodass Sie Ablaufverfolgungen identifizieren können, die jeder Benutzeranforderung zugeordnet sind, und sie mit anderen Ereignissen und Ausnahmeberichten in Beziehung setzen können.

Hinweis

Benötigen ich das Protokollerfassungsmodul? Dabei handelt es sich um einen nützlichen Adapter für die Protokollierung von Drittanbietern. Falls Sie nicht bereits NLog, log4Net oder „System.Diagnostics.Trace“ verwenden, können Sie auch einfach direkt Application Insights TrackTrace() aufrufen.

Hinweis

Am 31. März 2025 wird der Support für die auf Instrumentierungsschlüsseln basierende Erfassung eingestellt. Die Erfassung von Instrumentierungsschlüsseln funktioniert zwar weiterhin, wir stellen jedoch keine Updates und keinen Support mehr für das Feature bereit. Wechseln Sie zu Verbindungszeichenfolgen, damit Sie neue Funktionen nutzen können.

Installieren der Protokollierung in Ihrer App

Installieren Sie das von Ihnen gewählte Protokollierungsframework in Ihrem Projekt, was zu einem Eintrag in „app.config“ oder „web.config“ führen sollte.

 <configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener" type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

Konfigurieren von Application Insights für das Erfassen von Protokollen

Falls Sie dies noch nicht getan haben, fügen Sie Ihrem Projekt Application Insights hinzu. Es wird eine Option angezeigt, mit der Sie den Log Collector einfügen können.

Sie können auch im Projektmappen-Explorer mit der rechten Maustaste auf Application Insights konfigurieren klicken. Wählen Sie die Option Ablaufverfolgungssammlung konfigurieren.

Hinweis

Kein Application Insights-Menü und keine Log Collector-Option? Lesen Sie in der Problembehandlungnach.

Manuelle Installation

Verwenden Sie diese Methode, wenn der Projekttyp vom Application Insights-Installationsprogramm nicht unterstützt wird (z. B. bei einem Windows-Desktopprojekt).

  1. Wenn Sie log4Net oder NLog verwenden möchten, installieren Sie es in Ihrem Projekt.

  2. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und wählen Sie NuGet-Pakete verwalten aus.

  3. Suchen Sie nach „Application Insights“.

  4. Wählen Sie eins der folgenden Pakete aus:

Das NuGet-Paket installiert die erforderlichen Assemblys und ändert ggf. die Datei „web.config“ oder „app.config“.

ILogger

Beispiele für die Verwendung der Application Insights-ILogger-Implementierung mit Konsolenanwendungen und ASP.NET Core finden Sie i Artikel ApplicationInsightsLoggerProvider für .NET Core-ILogger-Protokolle.

Einfügen von Diagnoseprotokollaufrufen

Wenn Sie System.Diagnostics.Trace verwenden, wäre ein typischer Aufruf:

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

Wenn Sie log4net oder NLog bevorzugen, verwenden Sie:

    logger.Warn("Slow response - database01");

Verwenden von EventSource-Ereignissen

Sie können System.Diagnostics.Tracing.EventSource-Ereignisse so konfigurieren, dass Sie als Ablaufverfolgungen an Application Insights gesendet werden. Installieren Sie zunächst das Microsoft.ApplicationInsights.EventSourceListener-NuGet-Paket. Bearbeiten Sie anschließend den Abschnitt TelemetryModules der Datei ApplicationInsights.config.

    <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener">
      <Sources>
        <Add Name="MyCompany" Level="Verbose" />
      </Sources>
    </Add>

Für jede Datenquelle können Sie die folgenden Parameter festlegen:

  • Name gibt den Namen des zu erfassenden EventSource-Elements an.
  • Ebene gibt den zu erfassenden Protokolliergrad an: Critical, Error, Informational, LogAlways, Verbose oder Warning.
  • Schlüsselwörter (Optional) Gibt den ganzzahligen Wert der zu verwendenden Schlüsselwortkombinationen an.

Verwenden von DiagnosticSource-Ereignissen

Sie können System.Diagnostics.DiagnosticSource-Ereignisse so konfigurieren, dass sie als Ablaufverfolgungen an Application Insights gesendet werden. Installieren Sie zunächst das Microsoft.ApplicationInsights.DiagnosticSourceListener-NuGet-Paket. Bearbeiten Sie anschließend den Abschnitt „TelemetryModules“ der Datei ApplicationInsights.config.

    <Add Type="Microsoft.ApplicationInsights.DiagnosticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
      <Sources>
        <Add Name="MyDiagnosticSourceName" />
      </Sources>
    </Add>

Fügen Sie für jedes DiagnosticSource-Ereignis, das nachverfolgt werden soll, einen Eintrag hinzu, bei dem das Attribut Name auf den Namen von DiagnosticSource festgelegt ist.

Verwenden von ETW-Ereignissen

Sie können ETW-Ereignisse (Ereignisablaufverfolgung für Windows) so konfigurieren, dass sie als Ablaufverfolgungen an Application Insights gesendet werden. Installieren Sie zunächst das Microsoft.ApplicationInsights.EtwCollector-NuGet-Paket. Bearbeiten Sie anschließend den Abschnitt „TelemetryModules“ der Datei ApplicationInsights.config.

Hinweis

ETW-Ereignisse können nur gesammelt werden, wenn der Prozess, der das SDK hostet, unter einer Identität ausgeführt wird, die Mitglied von „Leistungsprotokollbenutzer“ oder „Administratoren“ ist.

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

Für jede Datenquelle können Sie die folgenden Parameter festlegen:

  • ProviderName ist der Name des zu erfassenden ETW-Anbieters.
  • ProviderGuid ist der GUID des zu erfassenden ETW-Anbieters. Er kann anstelle von ProviderName verwendet werden.
  • Ebene legt den zu erfassenden Protokolliergrad fest. Dieser kann Critical, Error, Informational, LogAlways, Verbose oder Warning sein.
  • Schlüsselwörter (Optional) Legt den ganzzahligen Wert der zu verwendenden Schlüsselwortkombinationen fest.

Direktes Verwenden der Ablaufverfolgungs-API

Sie können die API zur Application Insights-Ablaufverfolgung direkt aufrufen. Die Protokollierungsadapter verwenden diese API.

Beispiel:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

Ein Vorteil von TrackTrace ist, dass relativ lange Daten in die Nachricht eingefügt werden können. Sie können dort beispielsweise POST-Daten codieren.

Sie können Ihrer Nachricht auch einen Schweregrad hinzufügen. Wie bei anderen Telemetriedaten auch können Sie Eigenschaftswerte hinzufügen, um zu filtern oder nach verschiedenen Ablaufverfolgungen zu suchen. Beispiel:

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

Auf diese Weise können Sie in der Suche alle Nachrichten eines bestimmten Schweregrads, die im Zusammenhang mit einer bestimmten Datenbank stehen, einfach herausfiltern.

AzureLogHandler für OpenCensus Python

Mit dem Azure Monitor-Protokollhandler können Sie Python-Protokolle in Azure Monitor exportieren.

Instrumentieren Sie Ihre Anwendung mit dem OpenCensus Python SDK für Azure Monitor.

Dieses Beispiel zeigt, wie ein Protokoll auf Warnungsebene an Azure Monitor gesendet wird.

import logging

from opencensus.ext.azure.log_exporter import AzureLogHandler

logger = logging.getLogger(__name__)
logger.addHandler(AzureLogHandler(connection_string='InstrumentationKey=<your-instrumentation_key-here>'))
logger.warning('Hello, World!')

Untersuchen Ihrer Protokolle

Führen Sie Ihre App im Debugmodus aus, oder stellen Sie sie live bereit.

Wählen Sie im Übersichtsbereich im Application Insights-Portal die Option Suchen.

Sie haben beispielsweise folgende Möglichkeiten:

  • Filtern nach Protokollablaufverfolgungen oder nach Elementen mit bestimmten Eigenschaften
  • Untersuchen eines bestimmten Elements im Detail
  • Suchen Sie nach anderen Systemprotokolldaten, die sich auf dieselbe Benutzeranforderung beziehen (mit derselben „OperationId“).
  • Speichern der Konfiguration einer Seite als Favorit.

Hinweis

Wenn Ihre Anwendung eine große Menge von Daten sendet und Sie das Application Insights-SDK für ASP.NET Version 2.0.0-beta3 oder höher verwenden, wird möglicherweise die adaptive Stichprobenerstellung verwendet, bei der nur ein bestimmter Teil der Telemetriedaten übermittelt wird. Erfahren Sie mehr über das Erstellen von Stichproben.

Problembehandlung

Verzögerte Telemetrie, Überlastung des Netzwerks oder ineffiziente Übertragung

„System.Diagnostics.Tracing“ verfügt über ein Feature zum automatischen Leeren (Autoflush). Dies führt dazu, dass das SDK bei jedem Telemetrieelement eine Leerung durchführt. Dies ist nicht erwünscht und kann zu Problemen mit dem Protokollierungsadapter führen, z. B. zu verzögerter Telemetrie, Überlastung des Netzwerks, ineffizienter Übertragung usw.

Wie geht das mit Java?

In der Java-Instrumentierung ohne Code (empfohlen) werden die Protokolle standardmäßig erfasst. Verwenden Sie den Java 3.0-Agent.

Wenn Sie das Java-SDK verwenden, verwenden Sie die Java-Protokolladapter.

Keine Application Insights-Option im Kontextmenü des Projekts

  • Stellen Sie sicher, dass die Developer Analytics Tools auf diesem Entwicklungscomputer installiert sind. Suchen Sie in Visual Studio im Menü Extras>Erweiterungen und Updates nach Developer Analytics Tools. Wenn die Option nicht auf der Registerkarte Installiert angezeigt wird, öffnen Sie die Registerkarte Online und installieren sie.
  • Möglicherweise ist dies ein Projekttyp, der von den Developer Analytics Tools nicht unterstützt wird. Verwenden Sie die manuelle Installation.

Es gibt keine Option für die Protokolladapter im Konfigurationstool.

  • Installieren Sie zunächst das Protokollierungsframework.
  • Wenn Sie „System.Diagnostics.Trace“ verwenden, müssen Sie sicherstellen, dass es in web.config konfiguriert ist.
  • Vergewissern Sie sich, dass die aktuelle Version von Application Insights installiert ist. Wählen Sie in Visual Studio im Menü Extras>Erweiterungen und Updates aus, und öffnen Sie die Registerkarte Updates. Wenn die Developer Analytics-Tools hier aufgeführt werden, wählen Sie sie aus, um sie zu aktualisieren.

Eine Fehlermeldung „Instrumentationsschlüssel darf nicht leer sein“ wird angezeigt.

Sie haben möglicherweise das NuGet-Paket für die Protokollierungsadapter installiert, ohne Application Insights zu installieren. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf ApplicationInsights.config, und wählen Sie Application Insights aktualisieren aus. Sie werden aufgefordert, sich bei Azure anzumelden und eine Application Insights-Ressource zu erstellen oder eine vorhandenen Ressource wiederzuverwenden. Damit sollte das Problem behoben werden.

Es kann eine Weile dauern, bis alle Ereignisse und Anforderungen über die Pipeline abgerufen werden.

Wie viele Daten werden beibehalten?

Die Menge der beibehaltenen Daten hängt von mehreren Faktoren ab. Weitere Informationen finden Sie auf der Seite mit den Metriken für benutzerdefinierte Ereignisse im Abschnitt Grenzwerte.

Es werden einige Protokolleinträge nicht angezeigt, die ich erwartet habe.

Wenn Ihre Anwendung eine große Menge von Daten sendet und Sie das Application Insights-SDK für ASP.NET Version 2.0.0-beta3 oder höher verwenden, wird möglicherweise die adaptive Stichprobenerstellung verwendet, bei der nur ein bestimmter Teil der Telemetriedaten übermittelt wird. Erfahren Sie mehr über das Erstellen von Stichproben.

Nächste Schritte