EventActivityIdControl-Funktion (evntprov.h)

  • Artikel

Erstellt, abfragt und legt Aktivitätsbezeichner für die Verwendung in ETW-Ereignissen fest.

Syntax

ULONG EVNTAPI EventActivityIdControl(
  [in]      ULONG  ControlCode,
  [in, out] LPGUID ActivityId
);

Parameter

[in] ControlCode

Ein Steuerelementcode, der den auszuführenden Vorgang angibt.

  • EVENT_ACTIVITY_CTRL_GET_ID

    Legt den ActivityId-Parameter auf den Wert der Aktivitäts-ID des aktuellen Threads fest.

  • EVENT_ACTIVITY_CTRL_SET_ID

    Legt die Aktivitäts-ID des aktuellen Threads auf den Wert des ActivityId-Parameters fest.

  • EVENT_ACTIVITY_CTRL_CREATE_ID

    Legt den ActivityId-Parameter auf den Wert einer neu generierten lokal eindeutigen Aktivitäts-ID fest.

  • EVENT_ACTIVITY_CTRL_GET_SET_ID

    Tauscht die Werte des ActivityId-Parameters und der Aktivitäts-ID des aktuellen Threads aus. (Speichert den Wert der Aktivitäts-ID des aktuellen Threads, legt dann die Aktivitäts-ID des aktuellen Threads auf den Wert des ActivityId-Parameters und dann den ActivityId-Parameter auf den gespeicherten Wert fest.)

  • EVENT_ACTIVITY_CTRL_CREATE_SET_ID

    Legt den ActivityId-Parameter auf den Wert der Aktivitäts-ID des aktuellen Threads und dann die Aktivitäts-ID des aktuellen Threads auf den Wert einer neu generierten lokal eindeutigen Aktivitäts-ID fest.

[in, out] ActivityId

Ein Zeiger auf einen Puffer, der eine 128-Bit-Aktivitäts-ID enthält. Dieser Puffer kann in Abhängigkeit vom Wert des ControlCode-Parameters gelesen und/oder in geschrieben werden.

Rückgabewert

Gibt bei erfolgreicher Ausführung ERROR_SUCCESS zurück.

Hinweise

ETW-Ereignisse, die mit einer der EventWrite-APIs geschrieben wurden, enthalten ein 128-Bit-Feld "Aktivitäts-ID" und können optional ein 128-Bit-Feld "zugehörige Aktivitäts-ID" enthalten. Ablaufverfolgungsverarbeitungstools können die Werte dieser Felder verwenden, um Ereignisse in Gruppen zu organisieren, die als Aktivitäten bezeichnet werden.

  • Es wird davon ausgegangen, dass alle Ereignisse mit einer Aktivitäts-ID von 0 (d. h. GUID_NULL) nicht Teil einer Aktivität sind.
  • Es wird davon ausgegangen, dass alle Ereignisse, die eine bestimmte Aktivitäts-ID ungleich 0 aufweisen, Teil derselben Aktivität sind.
  • Um den Beginn der Aktivität anzugeben, sollte der Anbieter Opcode auf WINEVENT_OPCODE_START für das erste Ereignis mit einer bestimmten Aktivitäts-ID ungleich 0 (startereignis ) festlegen. Wenn die Aktivität logisch in einer anderen Aktivität geschachtelt ist, sollte der Anbieter das zugehörige Aktivitäts-ID-Feld des Startereignisses auf die ID der übergeordneten Aktivität festlegen.
  • Um das Ende der Aktivität anzugeben, sollte der Anbieter Opcode auf WINEVENT_OPCODE_STOP für das letzte Ereignis mit einer bestimmten Aktivitäts-ID ungleich 0 (das Stop-Ereignis ) festlegen.

Damit Aktivitäts-IDs nützlich sind, müssen neu generierte Aktivitäts-IDs lokal eindeutig sein, d. h. dieselbe ID darf nicht zweimal innerhalb der Ablaufverfolgung generiert werden.

Sie können Aktivitäts-IDs mit EventActivityIdControl erstellen, das lokal eindeutige IDs generiert, die garantiert für alle Prozesse auf dem lokalen System eindeutig sind, bis das System neu gestartet wird. Sie können auch eine GUID (global eindeutiger Bezeichner) als Aktivitäts-ID verwenden. Sie können eine GUID mithilfe einer API wie UuidCreate erstellen.

Benutzermodusthreads verfügen über einen threadlokalen 128-Bit-Aktivitäts-ID-Wert (die Aktivitäts-ID des Threads). Die Threadaktivitäts-ID wird beim Erstellen des Threads auf 0 (d. h. GUID_NULL) initialisiert. Die Threadaktivitäts-ID kann mit EventActivityIdControl gelesen oder aktualisiert werden. Die Threadaktivitäts-ID wird als Aktivitäts-ID für alle von EventWrite geschriebenen Ereignisse und für alle Ereignisse verwendet, die von EventWriteTransfer oder EventWriteEx geschrieben werden, wobei der ActivityId-ParameterNULL ist.

Wichtig

Eine Funktion, die die Aktivitäts-ID eines Threads ändert, sollte darauf achten, die ursprüngliche Aktivitäts-ID vor dem Beenden wiederherzustellen. Andernfalls beeinträchtigen die Änderungen der Funktion an der Aktivitäts-ID des Threads die Aktivitäten von Komponenten, die die Funktion aufrufen.

Verwenden einer explizit angegebenen Aktivitäts-ID

In Fällen, in denen Ihre Aktivitäten nicht auf einen einzelnen Thread beschränkt sind oder wenn Sie verhindern möchten, dass andere Komponenten die Aktivitäts-ID Ihres Threads überschreiben, können Sie Ereignisaktivitäten explizit über das ActivityId-Feld von EventWriteTransfer oder EventWriteEx angeben, anstatt die ID der automatischen Threadaktivität zu verwenden.

Wenn Manifeste und Nachrichtencompiler zum Schreiben von Ereignissen verwendet werden, verwenden die von MC.exe -um generierten Makros die Aktivitäts-ID des Threads, während die von MC.exe -km generierten Makros einen Aktivitäts-ID-Parameter unterstützen. Ursprünglich funktionierten die -um Makros nur im Benutzermodus, und die -km Makros funktionierten nur im Kernelmodus, sodass der Benutzermoduscode nur die Aktivitäts-ID des aktuellen Threads verwenden konnte. Ab MC.exe Version 10.0.17741 können die von MC.exe -km generierten Makros jedoch sowohl für den Benutzermodus als auch für den Kernelmodus verwendet werden, sodass Sie makros generieren MC.exe -km können, die einen Aktivitäts-ID-Parameter akzeptieren. (Der MC-generierte Code unterstützt das Festlegen der zugehörigen Aktivitäts-ID eines Ereignisses nicht.)

Wenn Sie TraceLoggingProvider.h zum Schreiben von Ereignissen verwenden, verwendet das TraceLoggingWrite-Makro die Aktivitäts-ID des Threads, während TraceLoggingWriteActivity Parameter für die Aktivitäts-ID und die zugehörige Aktivitäts-ID akzeptiert. Alternativ können Sie die C++-Klassen in TraceLoggingActivity.h für Ihre TraceLogging-Aktivitäten verwenden.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows Vista [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 [Desktop-Apps | UWP-Apps]
Zielplattform Windows
Kopfzeile evntprov.h
Bibliothek Advapi32.lib
DLL Advapi32.dll

Weitere Informationen

EventWriteTransfer