StartTraceA-Funktion (evntrace.h)

Die StartTrace-Funktion registriert und startet eine Ereignisablaufverfolgungssitzung.

Wichtig

Prozessübergreifende Ereignisablaufverfolgungssitzungen sind eine begrenzte Systemressource. Entwickler sollten das Starten von Ereignisablaufverfolgungssitzungen auf Kundencomputern vermeiden. Wenn Ereignisablaufverfolgungssitzungen erforderlich sind, 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 dann, wenn die Sammlung speziell für ein Szenario erforderlich ist, beenden Sie die Ablaufverfolgung, sobald das Szenario abgeschlossen ist, begrenzen Sie die Menge des von der Sitzung verwendeten Arbeitsspeichers. und verwenden Sie strenge Ereignisfilter, damit Sie keine unnötigen Ereignisse sammeln.

Syntax

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  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, beachtet die Groß-/Kleinschreibung nicht und muss eindeutig sein.

Wichtig

Verwenden Sie einen aussagekräftigen Namen für Ihre Sitzung, damit der Besitz 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 Ihren 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 startet, sollte Ihre Komponente die verwaiste Sitzung bereinigen, anstatt eine zweite Sitzung zu erstellen.

Diese Funktion kopiert den Sitzungsnamen, den Sie angeben, 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 Parameters Properties 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 die Filterung jetzt an StartTrace übergeben, wenn Sie systemweite private Protokollierungen starten. 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 Protokolliersitzung .

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 sind einige häufige Fehler und deren Ursachen aufgeführt.

  • ERROR_BAD_LENGTH

    Es trifft eine der folgenden Bedingungen zu:

    • Das Wnode.BufferSize-Element 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 Eigenschaften gibt eine Kombination von nicht gültigen Flags an.
    • Das Wnode.Guid-Element ist SystemTraceControlGuid, aber der Parameter InstanceName ist nicht KERNEL_LOGGER_NAME.
  • ERROR_ALREADY_EXISTS

    Eine Sitzung mit demselben Namen oder der gleichen 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-Member der Properties-Struktur angegeben wird.
    • LogFileMode und 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 nichtzero, und es sind keine MaximumFileSize-Bytes für die Protokolldatei verfügbar.
    • Das Laufwerk ist ein Systemlaufwerk, und es sind keine zusätzlichen 200 MB verfügbar.
    • MaximumFileSize ist 0, 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, verfügt er möglicherweise nicht über die Berechtigung, 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 Systemprotokollgern (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 änderungen wirksam werden.

      Beachten Sie, dass Protokollierungen Systemressourcen verwenden. Das Erhöhen der Anzahl von Protokollierungen auf dem System hat Leistungskosten, wenn diese Slots gefüllt sind. Dieses Limit besteht, 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 kreisförmige 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 Sie alle null (d. h. GUID_NULL) festProperties.Wnode.Guid, damit das ETW-System eine neue GUID für die Sitzung generieren kann.

Um eine private Protokollierungssitzung anzugeben, legen Sie Wnode.Guid-Member von Eigenschaften auf die Steuerelement-GUID des Anbieters und nicht auf die Steuerelement-GUID der privaten Protokolliersitzung 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 zutreffen:

  • Das Properties-ElementLogFileMode enthält das EVENT_TRACE_SYSTEM_LOGGER_MODE-Flag (bevorzugt).
  • Das Eigenschaften-ElementWnode.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 er mit anderen Komponenten in Konflikt steht, 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 Systemprotokollierungen 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 innerhalb eines Windows Server-Containers erstellt werden.
  • Systemprotokollierungen können das flag EVENT_TRACE_USE_PAGED_MEMORY nicht verwenden.
  • Vor Windows 10 Version 1703 können nicht mehr als zwei verschiedene Uhrtypen gleichzeitig von allen Systemprotokollierern 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 mit dem Uhrtyp "Systemzeit" zu starten, fehl, da die Aktivierung eines dritten Uhrentyps erforderlich wäre. Aufgrund dieser Einschränkung empfiehlt Microsoft dringend, dass Systemprotokollierer den Uhrtyp "Systemzeit" nicht verwenden.
  • Ab Windows 10 Version 1703 wurde die Einschränkung des Uhrtyps entfernt. Alle drei Takttypen können nun gleichzeitig von Systemloggern verwendet werden.

Um eine NT Kernel Logger-Sitzung 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 die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Aliases mit Code, der nicht codierungsneutral ist, 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 auf Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista
DLL Sechost.dll auf 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