TraceLoggingWriteActivity-Makro (traceloggingprovider.h)

Artikel
08/26/2023

Gibt ein TraceLogging-Ereignis mit den angegebenen Aktivitäts-IDs aus.

Syntax

void TraceLoggingWriteActivity(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  pActivityId,
  [in, optional]  pRelatedActivityId,
  [in, optional]  __VA_ARGS__
);

Parameter

[in] hProvider

Das Handle des TraceLogging-Anbieters , der zum Schreiben des Ereignisses verwendet werden soll.

[in] eventName

Ein kurzer und eindeutiger Name, der zum Identifizieren des Ereignisses verwendet werden soll. Hierbei muss es sich um ein Zeichenfolgenliteral und nicht um eine Variable handeln. Es darf keine eingebetteten '\0' Zeichen enthalten.

[in, optional] pActivityId

Die Aktivitäts-ID für das Ereignis oder NULL, um den Standardwert zu verwenden.

[in, optional] pRelatedActivityId

Die zugehörige Aktivitäts-ID für das Ereignis oder NULL für keine zugehörige Aktivitäts-ID.

[in, optional] __VA_ARGS__

Bis zu 99 zusätzliche Parameter zum Konfigurieren oder Hinzufügen von Feldern zum Ereignis. Jeder Parameter muss eines der TraceLogging Wrapper-Makros sein, z. B . TraceLoggingLevel, TraceLoggingKeyword oder TraceLoggingValue.

Wichtig

ProviderId, Level und Keyword sind die wichtigsten Mittel zum Filtern von Ereignissen. Andere Filterarten sind möglich, haben aber einen viel höheren Aufwand. Weisen Sie jedem Ereignis immer eine Nicht-Null-Ebene zu und Schlüsselwort (keyword).

Rückgabewert

Keine

Bemerkungen

Jeder Aufruf des TraceLoggingWriteActivity-Makros wird auf den Code erweitert, der zum Schreiben eines Ereignisses in ETW über das angegebene Anbieterhandle erforderlich ist.

TraceLoggingWriteActivity überprüft, ob der angegebene Anbieter registriert ist. Wenn der Anbieter nicht registriert ist, tut TraceLoggingWriteActivity nichts.
TraceLoggingWriteActivity überprüft, ob ein Consumer auf das Ereignis lauscht, als ob er TraceLoggingProviderEnabled aufruft. Wenn kein Consumer auf das Ereignis lauscht, tut TraceLoggingWriteActivity nichts.
Andernfalls wertet TraceLoggingWriteActivity die in den Argumenten angegebenen Laufzeitausdrücke aus, speichert die Ergebnisse, packt die erforderlichen Daten in ein Ereignis und ruft EventWriteTransfer auf, um das Ereignis an ETW zu senden.

Das generierte Ereignis wird wie folgt erstellt:

Die Anbieter-ID, der Anbietername und die Anbietergruppe des Ereignisses stammen aus dem hProvider-Parameter .
Der Name des Ereignisses stammt aus dem parameter eventName .
Die Aktivitäts-ID des Ereignisses stammt aus dem pActivityId-Parameter . Wenn pActivityId NULL ist, verwenden Benutzermodusereignisse die implizite Aktivitäts-ID des Threads, und Kernelmodusereignisse verwenden GUID_NULL.
Die zugehörige Aktivitäts-ID des Ereignisses stammt aus dem pRelatedActivityId-Parameter . Wenn pRelatedActivityId NULL ist, weist das Ereignis keine zugehörige Aktivitäts-ID auf.
Die Ereignisebene stammt aus dem Argument TraceLoggingLevel . Wenn kein TraceLoggingLevel-Argument vorhanden ist, ist die Ereignisebene 5 (WINEVENT_LEVEL_VERBOSE). Wenn mehr als ein TraceLoggingLevel-Argument vorhanden ist, wird das letzte Argument verwendet. Um eine effektive Ereignisfilterung zu ermöglichen, weisen Sie jedem Ereignis immer eine sinnvolle Ebene ungleich 0 zu.
Die Schlüsselwort (keyword) des Ereignisses stammt aus dem Argument TraceLoggingKeyword. Wenn kein TraceLoggingKeyword-Argument vorhanden ist, lautet der Schlüsselwort (keyword) des Ereignisses 0 (NONE). Wenn mehr als ein TraceLoggingKeyword-Argument vorhanden ist, werden die Werte zusammen OR'ed. Um eine effektive Ereignisfilterung zu ermöglichen, weisen Sie jedem Ereignis immer einen aussagekräftigen ungleich null Schlüsselwort (keyword) zu.
Andere Ereignisattribute können durch Argumente wie TraceLoggingOpcode, TraceLoggingDescription, TraceLoggingEventTag oder TraceLoggingChannel festgelegt werden.
Ereignisfelder können mithilfe von TraceLoggingStruct gruppiert werden.
Ereignisfelder werden durch Feldargumente wie TraceLoggingValue, TraceLoggingInt32, TraceLoggingHResult, TraceLoggingString usw. hinzugefügt. Weitere Informationen finden Sie unter TraceLogging Wrapper-Makros .

Beispiel:

TraceLoggingWriteActivity(
    g_hProvider,
    "MyEvent1",
    &myActivityGuid,
    NULL, // no related activity ID
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

Ein Aufruf von TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, args...) kann als Erweiterung auf Code wie folgt betrachtet werden:

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, aid, rid, N, data);
}

Hinweis

Jedes TraceLoggingWriteActivity-Makro überprüft automatisch TraceLoggingProviderEnabled , sodass das Ereignis nur geschrieben wird, wenn ein Consumer auf Ereignisse vom Anbieter lauscht. Daher ist es in der Regel nicht erforderlich, TraceLoggingProviderEnabled direkt aufzurufen. Alle Laufzeitausdrücke in args... werden nur ausgewertet, wenn das Ereignis aktiviert ist. Laufzeitausdrücke werden nicht mehr als einmal ausgewertet.

Wenn Sie komplexe Ereignisse generieren, erhalten Sie möglicherweise einen Compilerfehler, der darauf hinweist, dass die Zeile zu lang ist oder dass sich der Compiler außerhalb des Heapbereichs befindet. Dies tritt auf, wenn das TraceLoggingWriteActivity-Makro auf eine Zeile erweitert wird, die länger als vom Compiler unterstützt werden kann. In diesem Fall müssen Sie Ihre Veranstaltung vereinfachen.

Das TraceLoggingWriteActivity-Makro verwendet ein Array von EVENT_DATA_DESCRIPTOR , um Daten an ETW zu übertragen. Die maximale Anzahl der von ETW akzeptierten Deskriptoren beträgt 128. Da jeder Parameter möglicherweise die Verwendung von 0, 1 oder 2 Deskriptoren erfordert, ist es möglich, die Datendeskriptorgrenze (128) zu erreichen, bevor das Argumentlimit (99) erreicht wird.

Wichtig

Versuchen Sie, große Ereignisse zu vermeiden. ETW ist in erster Linie für die Behandlung kleiner Ereignisse konzipiert. TraceLoggingWriteActivity löscht automatisch alle Ereignisse, die zu groß sind. Die Größe des Ereignisses basiert auf der Summe der Header des Ereignisses (die von der ETW-Runtime hinzugefügt wurden), metadaten (z. B. Anbietername, Ereignisname, Feldnamen, Feldtypen) und Daten (Feldwerte). Wenn die Gesamtgröße des Ereignisses größer als 65535 ist oder die Consumersitzung eine Puffergröße verwendet, die kleiner als die Größe des Ereignisses ist, wird das Ereignis nicht aufgezeichnet.

Ein Aufruf von TraceLoggingWrite ist identisch mit einem Aufruf von TraceLoggingWriteActivity mit NULL für die Parameter pActivityId und pRelatedActivityId . Verwenden Sie TraceLoggingWriteActivity , wenn Sie Aktivitäts-IDs für ein Ereignis angeben müssen.

Informationen zur Semantik der Parameter ActivityId und RelatedActivityId finden Sie unter EventWriteTransfer.

Informationen zum Schreiben von Aktivitäten in ETW finden Sie unter EventActivityIdControl .

Weitere Informationen finden Sie unter TraceLoggingActivity für C++-Klassen, die beim Verwalten von TraceLogging-ETW-Aktivitäten helfen.

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	traceloggingprovider.h
Bibliothek	Advapi32.lib