StartTraceW-Funktion (evntrace.h)

  • Artikel

Die Funktion StartTrace registriert und startet eine Ereignisablaufverfolgungssitzung.

Wichtig

Prozessübergreifende Ereignisablaufverfolgungssitzungen sind eine begrenzte Systemressource. Entwickler sollten das Starten von Ereignisablaufverfolgungssitzungen auf Kundencomputern vermeiden. Wenn Ereignisablaufverfolgungssitzungen benötigt werden, sollten sie auf den kleinstmöglichen Bereich beschränkt werden: Verwenden Sie so wenige Sitzungen wie möglich, verwenden Sie nach Möglichkeit eine rein prozessinterne Sitzung (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC), starten Sie die Ablaufverfolgung nur, wenn die Sammlung speziell für ein Szenario erforderlich ist, beenden Sie die Ablaufverfolgung, sobald das Szenario abgeschlossen ist, begrenzen Sie die Menge an Arbeitsspeicher, die von der Sitzung verwendet wird, und verwenden Sie strenge Ereignisfilter, damit Sie keine unnötigen Ereignisse sammeln.

Syntax

ULONG WMIAPI StartTraceW(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCWSTR                 InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Parameter

[out] TraceHandle

Empfängt das Handle für die Ereignisablaufverfolgungssitzung zur späteren Verwendung mit APIs wie ControlTrace.

Verwenden Sie dieses Handle nicht, wenn die Funktion fehlschlägt. Vergleichen Sie das Sitzungshandle nicht mit INVALID_HANDLE_VALUE. Das Sitzungshandle ist 0, wenn das Handle ungültig ist.

[in] InstanceName

Null-beendete Zeichenfolge, die den Namen der Ereignisablaufverfolgungssitzung enthält. Der Sitzungsname ist auf 1.024 Zeichen beschränkt, unterscheidet die Groß-/Kleinschreibung nicht und muss eindeutig sein.

Wichtig

Verwenden Sie einen aussagekräftigen Namen für Ihre Sitzung, damit der Besitzer und die Nutzung der Sitzung anhand des Sitzungsnamens bestimmt werden können. Verwenden Sie keine GUID oder einen anderen nicht deterministischen oder nicht beschreibenden Wert. Fügen Sie keine zufälligen Ziffern an, um Den Sitzungsnamen eindeutig zu machen. ETW-Sitzungen sind eine begrenzte Ressource, sodass Ihre Komponente nicht mehrere Sitzungen starten sollte. Wenn die Sitzung Ihrer Komponente bereits ausgeführt wird, wenn Ihre Komponente gestartet wird, sollte Ihre Komponente die verwaiste Sitzung bereinigen, anstatt eine zweite Sitzung zu erstellen.

Diese Funktion kopiert den von Ihnen angegebenen Sitzungsnamen in den Offset, auf den das LoggerNameOffset-Element von Properties verweist.

[in, out] Properties

Zeiger auf eine EVENT_TRACE_PROPERTIES Struktur, die das Verhalten der Sitzung angibt. Im Folgenden sind die wichtigsten Elemente der festzulegenden Struktur aufgeführt:

  • Wnode.BufferSize
  • Wnode.Guid
  • Wnode.ClientContext
  • Wnode.Flags
  • LogFileMode
  • LogFileNameOffset
  • LoggerNameOffset

Abhängig vom Typ der Protokolldatei, die Sie erstellen möchten, müssen Sie möglicherweise auch einen Wert für MaximumFileSize angeben. Weitere Informationen zum Festlegen des Properties-Parameters und zum Verhalten der Sitzung finden Sie im Abschnitt Hinweise.

Ab Windows 10 Version 1703: Für eine bessere Leistung in prozessübergreifenden Szenarien können Sie beim Starten von systemweiten privaten Protokollierungen die Filterung an StartTrace übergeben. Sie müssen die neue EVENT_TRACE_PROPERTIES_V2-Struktur übergeben, um Filterinformationen einzuschließen. Weitere Informationen finden Sie unter Konfigurieren und Starten einer privaten Protokollierungssitzung .

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert ERROR_SUCCESS.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der Systemfehlercodes. Im Folgenden finden Sie einige häufige Fehler und deren Ursachen.

  • ERROR_BAD_LENGTH

    Es trifft eine der folgenden Bedingungen zu:

    • Der Wnode.BufferSize-Member von Properties gibt eine falsche Größe an.
    • Eigenschaften verfügen nicht über genügend Speicherplatz, um eine Kopie von InstanceName zu enthalten.

  • ERROR_INVALID_PARAMETER

    Es trifft eine der folgenden Bedingungen zu:

    • Eigenschaften sind NULL.
    • TraceHandle ist NULL.
    • Das LogFileNameOffset-Element von Properties ist ungültig.
    • Das LoggerNameOffset-Element von Properties ist ungültig.
    • Das LogFileMode-Element von Properties gibt eine Kombination von Flags an, die ungültig ist.
    • Das Wnode.Guid-Element ist SystemTraceControlGuid, aber der Parameter InstanceName ist nicht KERNEL_LOGGER_NAME.

  • ERROR_ALREADY_EXISTS

    Eine Sitzung mit demselben Namen oder derselben GUID wird bereits ausgeführt.

  • ERROR_BAD_PATHNAME

    Dieser Fehler kann aus einem der folgenden Gründe angezeigt werden:

    • Eine andere Sitzung verwendet bereits den Dateinamen, der vom LogFileNameOffset-Element der Properties-Struktur angegeben wird.
    • Sowohl LogFileMode als auch LogFileNameOffset sind null.

  • ERROR_DISK_FULL

    Auf dem Laufwerk ist nicht genügend freier Speicherplatz für die Protokolldatei vorhanden. Dies tritt auf, wenn:

    • MaximumFileSize ist ungleich null, und für die Protokolldatei sind keine MaximumFileSize-Bytes verfügbar.
    • Das Laufwerk ist ein Systemlaufwerk, und es sind keine zusätzlichen 200 MB verfügbar.
    • MaximumFileSize ist null, und es sind keine zusätzlichen 200 MB verfügbar.

    Wählen Sie ein Laufwerk mit mehr Speicherplatz aus, oder verringern Sie die in MaximumFileSize angegebene Größe (falls verwendet).

  • ERROR_ACCESS_DENIED

    Nur Benutzer mit Administratorrechten, Benutzer in der Gruppe Leistungsprotokollbenutzer und Dienste, die als LocalSystem, LocalService und NetworkService ausgeführt werden, können Ereignisablaufverfolgungssitzungen steuern. Um einem eingeschränkten Benutzer die Möglichkeit zu gewähren, Ablaufverfolgungssitzungen zu steuern, fügen Sie sie der Gruppe Leistungsprotokollbenutzer hinzu. Nur Benutzer mit Administratorrechten und Diensten, die als LocalSystem ausgeführt werden, können eine NT-Kernelprotokollierungssitzung steuern.

    Wenn der Benutzer Mitglied der Gruppe Leistungsprotokollbenutzer ist, ist er möglicherweise nicht berechtigt, die Protokolldatei im angegebenen Ordner zu erstellen.

  • ERROR_NO_SYSTEM_RESOURCES

    Es trifft eine der folgenden Bedingungen zu:

    • Die Protokollierungssitzung verwendet das Flag EVENT_TRACE_SYSTEM_LOGGER_MODE , und die maximale Anzahl von Systemprotokollierungen (8) wurde erreicht.

    • Die maximale Anzahl von Protokollierungssitzungen auf dem System wurde erreicht. Es können keine neuen Protokollierungen erstellt werden, bis eine Protokollierungssitzung beendet wurde. Auf den meisten Systemen beträgt die maximale Anzahl von Protokollierungssitzungen 64.

      Sie können die maximale Anzahl von Protokollierungssitzungen für ein System ändern, indem Sie den REG_DWORD Schlüssel unter HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggersbearbeiten. Zulässige Werte sind 32 bis einschließlich 256. Ein Neustart ist erforderlich, damit jede Änderung wirksam wird.

      Beachten Sie, dass Protokollierungen Systemressourcen verwenden. Das Erhöhen der Anzahl von Protokollierungen auf dem System verursacht Leistungseinbußen, wenn diese Slots gefüllt sind. Dieser Grenzwert ist vorhanden, um eine übermäßige Nutzung von Systemressourcen zu verhindern.

      Wichtig

      Der Grenzwert sollte nur manuell von einem Systemadministrator angepasst werden, um bestimmte Szenarien zu ermöglichen. Die EtwMaxLoggers-Einstellung darf nicht automatisch von einem Programm oder Treiber geändert werden.

      Vor Windows 10 Version 1709 ist dies eine feste Obergrenze von 64 Protokollierungen für nicht private Protokollierungen.

Bemerkungen

Ereignisablaufverfolgungscontroller rufen diese Funktion auf.

Die Sitzung bleibt aktiv, bis die Sitzung beendet wird, der Computer neu gestartet wird, ein E/A-Fehler auftritt oder die maximale Dateigröße für nicht zirkuläre Protokolle erreicht wird. Um eine Ereignisablaufverfolgungssitzung zu beenden, rufen Sie die ControlTrace-Funktion auf, und legen Sie den ControlCode-Parameter auf EVENT_TRACE_CONTROL_STOP fest.

Sie können nicht mehr als eine Sitzung mit derselben Sitzungs-GUID starten (wie durch Properties.Wnode.Guidangegeben). In den meisten Fällen legen Properties.Wnode.Guid Sie alle null (d. h. GUID_NULL) fest, damit das ETW-System eine neue GUID für die Sitzung generieren kann.

Um eine private Protokollierungssitzung anzugeben, legen Sie das Wnode.Guid-Element von Eigenschaften auf die Steuerelement-GUID des Anbieters und nicht auf die Steuerelement-GUID der privaten Protokollierungssitzung fest. Der Anbieter muss die GUID registriert haben, bevor Sie StartTrace aufrufen.

Sie verwenden diese Funktion nicht, um eine globale Protokollierungssitzung zu starten (veraltet). Ausführliche Informationen zum Starten einer globalen Protokollierungssitzung finden Sie unter Konfigurieren und Starten der globalen Protokollierungssitzung.

Systemprotokollierung

Damit die Protokollierung eine Systemprotokollierung ist und Ereignisse von SystemTraceProvider oder anderen Systemanbietern empfängt, muss einer der folgenden Punkte zutrifft:

  • Das EigenschaftenelementLogFileMode enthält das EVENT_TRACE_SYSTEM_LOGGER_MODE-Flag (bevorzugt).
  • Das EigenschaftenmitgliedWnode.Guid ist auf SystemTraceControlGuid oder GlobalLoggerGuid festgelegt (veraltet– sollte nicht für neuen Code verwendet werden, da es zu Konflikten mit anderen Komponenten führt, die ebenfalls versuchen, diese GUIDs zu verwenden).
  • InstanceName ist auf KERNEL_LOGGER_NAME festgelegt (veraltet– sollte nicht für neuen Code verwendet werden, da es zu Konflikten mit anderen Komponenten führt, die ebenfalls versuchen, diesen Namen zu verwenden).

Hinweis

 Eine Systemprotokollierung muss den EnableFlags-Member der EVENT_TRACE_PROPERTIES-Struktur festlegen, um anzugeben, welche SystemTraceProvider-Ereignisse in die Ablaufverfolgung einbezogen werden sollen.

Da Systemprotokollierer spezielle Kernelereignisse empfangen, unterliegen sie zusätzlichen Einschränkungen:

  • Es dürfen nicht mehr als 8 Systemlogger auf demselben System aktiv sein.
  • Systemprotokollierungen können nicht in einem Windows Server-Container erstellt werden.
  • Systemprotokollierer können das flag EVENT_TRACE_USE_PAGED_MEMORY nicht verwenden.
  • Vor Windows 10 Version 1703 können nicht mehr als zwei verschiedene Takttypen gleichzeitig von systemloggern verwendet werden. Wenn beispielsweise eine aktive Systemprotokollierung den Takttyp "CPU-Zykluszähler" und eine andere aktive Systemprotokollierung den Takttyp "Abfrageleistungszähler" verwendet, schlägt jeder Versuch, eine Systemprotokollierung mithilfe des Takttyps "Systemzeit" zu starten, fehl, da die Aktivierung eines dritten Takttyps erforderlich wäre. Aufgrund dieser Einschränkung empfiehlt Microsoft dringend, dass Systemprotokollierer den Takttyp "Systemzeit" nicht verwenden.
  • Ab Windows 10 Version 1703 wurde die Einschränkung des Takttyps entfernt. Alle drei Takttypen können nun gleichzeitig von Systemloggern verwendet werden.

Um eine NT-Kernelprotokollierungssitzung anzugeben (veraltet), legen Sie InstanceName auf KERNEL_LOGGER_NAME und das Wnode.Guid-Element von Properties auf SystemTraceControlGuid fest. Wenn Sie die GUID nicht als SystemTraceControlGuid angeben, überschreibt ETW den GUID-Wert und legt ihn auf SystemTraceControlGuid fest.

Beispiele

Ein Beispiel, das StartTrace verwendet, finden Sie unter Konfigurieren und Starten einer Ereignisablaufverfolgungssitzung.

Hinweis

Der evntrace.h-Header definiert StartTrace als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile evntrace.h
Bibliothek Sechost.lib auf Windows 8.1 und Windows Server 2012 R2; Advapi32.lib unter Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista
DLL Sechost.dll unter Windows 8.1 und Windows Server 2012 R2; Advapi32.dll unter Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista

Weitere Informationen

ControlTrace

EVENT_TRACE_PROPERTIES