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

  • Artikel

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 aus Ihrer Anwendung zusammengeführt. Sie können Sie verwenden, um Ablaufverfolgungen im Zusammenhang mit den einzelnen Benutzeranforderungen zu identifizieren und sie mit anderen Ereignissen und Ausnahmeberichten zu korrelieren.

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 Application Insights TrackTrace() direkt 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

Fügen Sie Ihrem Projekt Application Insights hinzu, wenn Sie dies noch nicht getan haben. Es gibt eine Option zum Einschließen des Protokollsammlers.

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. Wenn es sich beispielsweise um ein Windows-Desktopprojekt handelt.

  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 jede Diagnosequelle, die nachverfolgt werden soll, einen Eintrag hinzu, bei dem das Attribut Name auf den Namen Ihrer Diagnosequelle 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" } });

Jetzt können Sie unter Transaktionssuche problemlos alle Nachrichten eines bestimmten Schweregrads filtern, die eine bestimmte Datenbank betreffen.

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 Ihrer App im Application Insights-Portal die Option Transaktionssuche aus.

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 Vorgangs-ID).
  • 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 Sampling.

Problembehandlung

Antworten auf häufig gestellte Fragen

Was bewirkt verzögerte Telemetrie, ein überlastetes Netzwerk und ineffiziente Übertragung?

„System.Diagnostics.Tracing“ verfügt über ein Feature zum automatischen Leeren (Autoflush). Dieses Feature 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, einer Überlastung des Netzwerks sowie ineffizienter Übertragung.

Wie geht das mit Java?

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

Der Java-Agent von Application Insights sammelt vorkonfiguriert Protokolle von Log4j, Logback und java.util.logging.

Warum ist keine Application Insights-Option im Kontextmenü des Projekts vorhanden?

  • Stellen Sie sicher, dass die Developer Analytics Tools auf diesem Entwicklungscomputer installiert sind. Navigieren Sie in Visual Studio zu Extras>Erweiterungen und Updates, und suchen Sie 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.

Warum gibt es 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. Navigieren Sie in Visual Studio zu Extras>Erweiterungen und Updates, und öffnen Sie die Registerkarte Updates. Wenn Developer Analytics Tools hier aufgeführt wird, wählen Sie diese Option aus, um sie zu aktualisieren.

Warum erhalte ich die Fehlermeldung „Instrumentierungsschlüssel darf nicht leer sein“?

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.

Warum werden einige Protokolleinträge nicht angezeigt, die ich erwartet habe?

Vielleicht sendet Ihre Anwendung große Datenmengen und Sie verwenden das Application Insights SDK für ASP.NET Version 2.0.0-beta3 oder höher. In diesem Fall könnte das adaptive Sampling aktiv sein und nur einen Teil Ihrer Telemetriedaten senden. Erfahren Sie mehr über Sampling.

Nächste Schritte