Konfigurieren der Ablaufverfolgung
In diesem Thema wird Folgendes beschrieben: das Aktivieren der Ablaufverfolgung, das Konfigurieren von Ablaufverfolgungsquellen zum Ausgeben von Ablaufverfolgungen, das Festlegen von Ablaufverfolgungsebenen, das Festlegen der Aktivitätsablaufverfolgung und -weitergabe zur Unterstützung der End-to-End-Ablaufverfolgungskorrelation sowie das Festlegen von Ablaufverfolgungslistenern für den Zugriff auf Ablaufverfolgungen.
Empfehlungen zu Ablaufverfolgungseinstellungen in der Produktions- oder Debugumgebung finden Sie unter Empfohlene Einstellungen für Ablaufverfolgung und Nachrichtenprotokollierung.
Wichtig
Unter Windows 8 müssen Sie die Anwendung mit erhöhten Rechten (als Administrator) ausführen, damit die Anwendung Ablaufverfolgungsprotokolle generieren kann.
Aktivieren der Ablaufverfolgung
Windows Communication Foundation (WCF) gibt folgende Daten für die Diagnoseablaufverfolgung aus:
Ablaufverfolgungen für Verarbeitungsmeilensteine in allen Komponenten der Anwendungen (beispielsweise Vorgangsaufrufe, Codeausnahmen, Warnungen und andere wichtige Verarbeitungsereignisse).
Windows-Fehlerereignisse bei Fehlern der Ablaufverfolgungsfunktion. Weitere Informationen finden Sie unter Die Ereignisprotokollierung in WCF.
Die WCF-Ablaufverfolgung basiert auf System.Diagnostics. Definieren Sie in der Konfigurationsdatei oder im Code Ablaufverfolgungsquellen, wenn Sie die Ablaufverfolgung verwenden möchten. WCF definiert eine Ablaufverfolgungsquelle für jede WCF-Assembly. Die System.ServiceModel-Ablaufverfolgungsquelle ist die allgemeinste WCF-Ablaufverfolgungsquelle. Sie zeichnet Verarbeitungsmeilensteine im WCF-Kommunikationsstapel vom Eintreten/Verlassen des Transports bis zum Eintreten/Verlassen des Benutzercodes auf. Die System.ServiceModel.MessageLogging-Ablaufverfolgungsquelle zeichnet alle Nachrichten auf, die das System durchlaufen.
Die Ablaufverfolgung ist standardmäßig nicht aktiviert. Um die Ablaufverfolgung zu aktivieren, müssen Sie einen Ablaufverfolgungslistener erstellen und eine andere Ablaufverfolgungsebene als „Off“ für die ausgewählte Ablaufverfolgungsquelle in der Konfiguration festlegen. Andernfalls generiert WCF keine Ablaufverfolgungen. Wenn Sie keinen Listener angeben, ist die Ablaufverfolgung automatisch deaktiviert. Wenn Sie einen Listener definieren, jedoch keine Ebene angeben, wird die Ebene standardmäßig auf "Off" festgelegt. Das bedeutet, dass keine Ablaufverfolgung ausgegeben wird.
Wenn Sie WCF-Erweiterungspunkte (z. B. aufrufende Instanzen für benutzerdefinierte Vorgänge) verwenden, müssen Sie eigene Ablaufverfolgungen ausgeben. Das liegt daran, dass WCF bei Implementierung eines Erweiterungspunkts die Standardablaufverfolgungen nicht mehr im Standardpfad ausgeben kann. Wenn Sie keine Unterstützung für eine manuelle Ablaufverfolgung durch Ausgabe von Ablaufverfolgungen implementieren, werden die erwarteten Ablaufverfolgungen möglicherweise nicht angezeigt.
Sie können die Ablaufverfolgung konfigurieren, indem Sie die Konfigurationsdatei der Anwendung bearbeiten – entweder „Web.config“ für im Web gehostete Anwendungen oder „Appname.exe.config“ für selbst gehostete Anwendungen. Das folgende Beispiel zeigt eine solche Bearbeitung. Weitere Informationen zu diesen Einstellungen finden Sie im Abschnitt „Konfigurieren von Ablaufverfolgungslistenern zur Verwendung von Ablaufverfolgungen“.
<configuration>
<system.diagnostics>
<sources>
<source name="System.ServiceModel"
switchValue="Information, ActivityTracing"
propagateActivity="true">
<listeners>
<add name="traceListener"
type="System.Diagnostics.XmlWriterTraceListener"
initializeData= "c:\log\Traces.svclog" />
</listeners>
</source>
</sources>
</system.diagnostics>
</configuration>
Hinweis
Um die Konfigurationsdatei eines WCF-Dienstprojekts in Visual Studio zu bearbeiten, klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf die Konfigurationsdatei der Anwendung (entweder „Web.config“ für im Web gehostete Anwendungen oder „Appname.exe.config“ für selbst gehostete Anwendungen). Wählen Sie dann das Kontextmenüelement WCF-Konfiguration bearbeiten aus. Dadurch wird das Configuration Editor-Tool (SvcConfigEditor.exe) gestartet. Dieses Tool ermöglicht die Erstellung und Bearbeitung von Konfigurationseinstellungen für WCF-Dienste über eine grafische Benutzeroberfläche.
Konfigurieren von Ablaufverfolgungsquellen zum Ausgeben von Ablaufverfolgungen
WCF definiert eine Ablaufverfolgungsquelle für jede Assembly. Innerhalb einer Assembly generierte Ablaufverfolgungen werden von den Listenern verwendet, die für diese Quelle definiert sind. Folgende Ablaufverfolgungsquellen sind definiert:
System.ServiceModel: Protokolliert alle Phasen der WCF-Verarbeitung, jedes Lesen der Konfiguration, Verarbeiten einer Nachricht beim Transport, jede Sicherheitsverarbeitung, das Senden einer Nachricht im Benutzercode und Ähnliches.
System.ServiceModel.MessageLogging: Protokolliert alle Nachrichten, die das System durchlaufen.
System.IdentityModel.
System.ServiceModel.Activation.
System.IO.Log: Protokollierung für die .NET Framework-Schnittstelle im gemeinsamen Protokolldateisystem (Common Log File System, CLFS).
System.Runtime.Serialization: Protokolliert das Lesen oder Schreiben von Objekten.
CardSpace.
Das folgenden Konfigurationsbeispiel veranschaulicht, wie Sie jede Ablaufverfolgungsquelle so konfigurieren können, dass sie den gleichen (freigegebenen) Listener verwendet:
<configuration>
<system.diagnostics>
<sources>
<source name="System.ServiceModel"
switchValue="Information, ActivityTracing"
propagateActivity="true">
<listeners>
<add name="xml" />
</listeners>
</source>
<source name="CardSpace">
<listeners>
<add name="xml" />
</listeners>
</source>
<source name="System.IO.Log">
<listeners>
<add name="xml" />
</listeners>
</source>
<source name="System.Runtime.Serialization">
<listeners>
<add name="xml" />
</listeners>
</source>
<source name="System.IdentityModel">
<listeners>
<add name="xml" />
</listeners>
</source>
</sources>
<sharedListeners>
<add name="xml"
type="System.Diagnostics.XmlWriterTraceListener"
initializeData="c:\log\Traces.svclog" />
</sharedListeners>
</system.diagnostics>
</configuration>
Sie können außerdem benutzerdefinierte Ablaufverfolgungsquellen hinzufügen, um Ablaufverfolgungsquellen im Benutzercode auszugeben (wie im folgenden Code dargestellt):
<system.diagnostics>
<sources>
<source name="UserTraceSource" switchValue="Warning, ActivityTracing" >
<listeners>
<add name="xml"
type="System.Diagnostics.XmlWriterTraceListener"
initializeData="C:\logs\UserTraces.svclog" />
</listeners>
</source>
</sources>
<trace autoflush="true" />
</system.diagnostics>
Weitere Informationen zum Erstellen benutzerdefinierter Ablaufverfolgungsquellen finden Sie unter Erweitern der Ablaufverfolgung.
Konfigurieren von Ablaufverfolgungslistenern zur Verwendung von Ablaufverfolgungen
Zur Laufzeit übergibt WCF Ablaufverfolgungsdaten an die Listener, die die Daten verarbeiten. WCF stellt verschiedene vordefinierte Listener für System.Diagnostics bereit. Diese Listener unterscheiden sich hinsichtlich des Formats, das für die Ausgabe verwendet wird. Sie können auch benutzerdefinierte Listenertypen hinzufügen.
Mit add können Sie den Namen und den Typ des Ablaufverfolgungslisteners angeben, den Sie verwenden möchten. In unserer Beispielkonfiguration haben wir den Listener traceListener genannt und den standardmäßigen .NET Framework-Ablaufverfolgungslistener (System.Diagnostics.XmlWriterTraceListener) als zu verwendenden Typ angegeben. Sie können jeder Quelle beliebig viele Ablaufverfolgungslistener hinzufügen. Wenn der Ablaufverfolgungslistener die Ablaufverfolgung an eine Datei ausgibt, müssen Sie den Speicherort der Ausgabedatei angeben und sie in der Konfigurationsdatei benennen. Legen Sie dazu initializeData auf den Namen der Datei für diesen Listener fest. Wenn Sie keinen Dateinamen angeben, wird basierend auf dem verwendeten Listenertyp ein beliebiger Dateiname generiert. Wenn XmlWriterTraceListener verwendet wird, wird ein Dateiname ohne Erweiterung generiert. Beim Implementieren eines benutzerdefinierten Listeners können Sie dieses Attribut auch verwenden, um andere Initialisierungsdaten als den Dateinamen zu erhalten. Sie können für dieses Attribut z. B. einen Datenbankbezeichner angeben.
Sie können einen benutzerdefinierten Ablaufverfolgungslistener konfigurieren, um Ablaufverfolgungen zu übertragen, z. B. an eine Remotedatenbank. Stellen Sie beim Bereitstellen von Anwendungen eine ordnungsgemäße Zugriffsteuerung für die Protokolle auf dem Remotecomputer sicher.
Sie können einen Ablaufverfolgungslistener auch programmgesteuert konfigurieren. Weitere Informationen finden Sie unter Vorgehensweise: Erstellen und Initialisieren von Ablaufverfolgungslistenern sowie unter Creating a Custom TraceListener (Erstellen eines benutzerdefinierten Ablaufverfolgungslisteners).
Achtung
Da System.Diagnostics.XmlWriterTraceListener nicht threadsicher ist, werden Ressourcen durch die Ablaufverfolgungsquelle bei der Ausgabe von Ablaufverfolgungen möglicherweise exklusiv gesperrt. Wenn viele Threads Ablaufverfolgungen an eine Ablaufverfolgungsquelle ausgeben, die für die Verwendung dieses Listeners konfiguriert ist, treten möglicherweise Ressourcenkonflikte auf. Das kann die Leistung erheblich beeinträchtigen. Implementieren Sie einen threadsicheren benutzerdefinierten Listener, um dieses Problem zu beheben.
Ablaufverfolgungsebene
Die Ablaufverfolgungsebene wird von der switchValue-Einstellung der Ablaufverfolgungsquelle gesteuert. Die verfügbaren Ablaufverfolgungsebenen werden in der folgenden Tabelle beschrieben.
| Ablaufverfolgungsebene | Art der verfolgten Ereignisse | Inhalt der verfolgten Ereignisse | Verfolgte Ereignisse | Zielgruppe |
|---|---|---|---|---|
| Aus | – | – | Keine Ablaufverfolgungen werden ausgegeben. | – |
| Kritisch | „Negative“ Ereignisse: Ereignisse, die auf eine unerwartete Verarbeitung oder auf eine Fehlerbedingung hindeuten. | Nicht behandelte Ausnahmen (einschließlich der folgenden) werden protokolliert: - OutOfMemoryException - ThreadAbortException (von der CLR wird ein beliebiger ThreadAbortExceptionHandler aufgerufen) - StackOverflowException (kann nicht abgefangen werden) - ConfigurationErrorsException - SEHException - Startfehler der Anwendung - Failfast-Ereignisse - Hängenbleiben des Systems - Nicht verarbeitbare Nachrichten: Nachrichtenablaufverfolgungen, die Anwendungsfehler verursachen |
Administrators Anwendungsentwickler |
|
| Fehler | „Negative“ Ereignisse: Ereignisse, die auf eine unerwartete Verarbeitung oder auf eine Fehlerbedingung hindeuten. | Eine unerwartete Verarbeitung ist aufgetreten. Die Anwendung konnte die Aufgabe nicht wie erwartet ausführen. Die Anwendung wird jedoch weiter ordnungsgemäß ausgeführt. | Alle Ausnahmen werden protokolliert. | Administrators Anwendungsentwickler |
| Warnung | „Negative“ Ereignisse: Ereignisse, die auf eine unerwartete Verarbeitung oder auf eine Fehlerbedingung hindeuten. | Ein mögliches Problem ist aufgetreten oder tritt möglicherweise auf, die Anwendung funktioniert jedoch noch ordnungsgemäß. Allerdings ist nicht sicher, dass sie weiterhin ordnungsgemäß ausgeführt wird. | - Die Anwendung empfängt mehr Anforderungen als die Einschränkungseinstellungen zulassen. - Die empfangende Warteschlange hat nahezu die maximal konfigurierte Kapazität erreicht. - Ein Timeout wurde überschritten. - Die Anmeldeinformationen werden abgelehnt. |
Administrators Anwendungsentwickler |
| Information | „Positive“ Ereignisse: Ereignisse, die erfolgreiche Meilensteine kennzeichnen. | Wichtige und erfolgreiche Meilensteine der Anwendungsausführung, unabhängig davon, ob die Anwendung ordnungsgemäß funktioniert. | In der Regel werden Meldungen generiert, die bei der Überwachung und Diagnose des Systemstatus, der Leistungsmessung oder Profilerstellung nützlich sind. Solche Informationen können zur Kapazitätsplanung und Leistungsverwaltung genutzt werden: - Kanäle werden erstellt. - Endpunktlistener werden erstellt. - Eine Nachricht tritt in die Transportphase ein oder verlässt sie. - Ein Sicherheitstoken wird abgerufen. - Eine Konfigurationseinstellung wird gelesen. |
Administrators Anwendungsentwickler Produktentwickler |
| Ausführlich | „Positive“ Ereignisse: Ereignisse, die erfolgreiche Meilensteine kennzeichnen. | Untergeordnete Ereignisse für Benutzercode und Wartung werden ausgegeben. | Im Allgemeinen können Sie diese Ebene zum Debuggen oder zur Anwendungsoptimierung verwenden. - Verstandener Nachrichtenheader |
Administrators Anwendungsentwickler Produktentwickler |
| ActivityTracing | Ablaufereignisse zwischen Verarbeitungsaktivitäten und Komponenten. | Diese Ebene ermöglicht es Administratoren und Entwicklern, Anwendungen in einer Anwendungsdomäne zu korrelieren: - Ablaufverfolgungen für Aktivitätsgrenzen wie Start/Stopp - Ablaufverfolgungen für Übertragungen |
Alle | |
| Alle | Die Anwendung funktioniert möglicherweise ordnungsgemäß. Alle Ereignisse werden ausgegeben. | Alle vorherigen Ereignisse. | Alle |
Die Ebenen von Verbose bis Critical bauen aufeinander auf, d. h. jede Ablaufverfolgungsebene umfasst alle Ebenen darüber, außer der Off-Ebene. Beispielsweise empfängt en Listener, der die Warning-Ebene überwacht, Critical-, Error- and Warning-Ablaufverfolgungen. Die All-Ebene schließt Ereignisse von Verbose- bis Critical- und ActivityTracing-Ereignissen ein.
Achtung
Die Ebenen "Information", "Verbose" und "ActivityTracing" generieren eine Vielzahl von Ablaufverfolgungen, was sich negativ auf den Nachrichtendurchsatz auswirken kann, wenn alle verfügbaren Ressourcen des Computers belegt sind.
Konfigurieren der Aktivitätsablaufverfolgung und Weitergabe für die Korrelation
Mit dem für das activityTracing-Attribut angegebenen switchValue-Wert wird die Aktivitätsablaufverfolgung aktiviert, die Ablaufverfolgungen für Aktivitätsgrenzen und Übertragungen innerhalb von Endpunkten ausgibt.
Hinweis
Wenn Sie bestimmte Erweiterungsfunktionen in WCF verwenden, wird möglicherweise eine Ausnahme vom Typ NullReferenceException ausgelöst, wenn die Aktivitätsablaufverfolgung aktiviert ist. Um dieses Problem zu beheben, überprüfen Sie die Konfigurationsdatei der Anwendung und stellen sicher, dass das switchValue-Attribut für die Ablaufverfolgungsquelle nicht auf activityTracing festgelegt wurde.
Das propagateActivity-Attribut gibt an, ob die Aktivität an andere Endpunkte weitergegeben werden soll, die an dem Nachrichtenaustausch teilnehmen. Wenn Sie diesen Wert auf true festlegen, können Sie anhand von Ablaufverfolgungsdateien, die durch zwei Endpunkte generiert wurden, feststellen, wie eine Reihe von Ablaufverfolgungen an einem Endpunkt zu einer Reihe von Ablaufverfolgungen an einem anderen Endpunkt übergegangen sind.
Weitere Informationen zur Aktivitätsablaufverfolgung und -weitergabe finden Sie unter Weitergabe.
Beide booleschen Werte (propagateActivity und ActivityTracing) gelten für die System.ServiceModel-Ablaufverfolgungsquelle. Der ActivityTracing-Wert gilt außerdem für alle Ablaufverfolgungsquellen – einschließlich WCF und benutzerdefinierte Quellen.
Das propagateActivity-Attribut kann nicht bei benutzerdefinierten Ablaufverfolgungsquellen verwendet werden. Stellen Sie bei der Aktivitäts-ID-Weitergabe in Benutzercode sicher, dass Sie ActivityTracing von ServiceModel nicht festlegen, während das propagateActivity-Attribute von ServiceModel noch auf true festgelegt ist.