TraceLoggingWrite-Makro (traceloggingprovider.h)

Artikel
08/26/2023

Gibt ein TraceLogging-Ereignis aus.

Syntax

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [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. Dies muss ein Zeichenfolgenliteral und keine Variable sein. Es darf keine eingebetteten '\0' Zeichen enthalten.

[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 Ebene ungleich 0 (null) zu, und Schlüsselwort (keyword).

Rückgabewert

Keine

Bemerkungen

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

TraceLoggingWrite überprüft, ob der angegebene Anbieter registriert ist. Wenn der Anbieter nicht registriert ist, bewirkt TraceLoggingWrite nichts.
TraceLoggingWrite überprüft, ob ein Consumer auf das Ereignis lauscht, als ob er TraceLoggingProviderEnabled aufruft. Wenn kein Consumer auf das Ereignis lauscht, bewirkt TraceLoggingWrite nichts.
Andernfalls wertet TraceLoggingWrite 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 eventName-Parameter .
Im Benutzermodus stammt die Aktivitäts-ID des Ereignisses aus der id der impliziten Aktivität des Threads. Im Kernelmodus wird die Aktivitäts-ID des Ereignisses GUID_NULL.
Das Ereignis weist keine zugehörige Aktivitäts-ID auf.
Die Ebene des Ereignisses 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 zu, die nicht null ist.
Die Schlüsselwort (keyword) des Ereignisses stammt aus dem Argument TraceLoggingKeyword. Wenn kein TraceLoggingKeyword-Argument vorhanden ist, ist 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:

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

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

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

Hinweis

Jedes TraceLoggingWrite-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 angibt, dass die Zeile zu lang ist oder dass der Compiler nicht mehr im Heapbereich ist. Dies tritt auf, wenn das TraceLoggingWrite-Makro auf eine Zeile erweitert wird, die länger ist, als vom Compiler unterstützt werden kann. In diesem Fall müssen Sie Ihr Ereignis vereinfachen.

Das TraceLoggingWrite-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, den Datendeskriptorgrenzwert (128) zu erreichen, bevor der Argumentgrenzwert erreicht wird (99).

Wichtig

Versuchen Sie, große Ereignisse zu vermeiden. ETW ist in erster Linie für die Behandlung kleiner Ereignisse konzipiert. TraceLoggingWrite löscht automatisch alle Ereignisse, die zu groß sind. Die Größe des Ereignisses basiert auf der Summe der Header des Ereignisses (hinzugefügt von der ETW-Laufzeit), 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 entspricht 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.

Beispiele

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider,  // Name of the provider handle
    "MyProvider", // Human-readable name of the provider
    // ETW Control GUID: {b3864c38-4273-58c5-545b-8b3608343471}
    (0xb3864c38,0x4273,0x58c5,0x54,0x5b,0x8b,0x36,0x08,0x34,0x34,0x71));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

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

Weitere Informationen

EventWriteTransfer

TraceLoggingWriteActivity

TraceLogging Wrapper-Makros