Macro TraceLoggingWrite (traceloggingprovider.h)

Articolo
03/08/2023

Genera un evento TraceLogging.

Sintassi

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  __VA_ARGS__
);

Parametri

[in] hProvider

Handle del provider TraceLogging da usare per la scrittura dell'evento.

[in] eventName

Nome breve e univoco da usare per identificare l'evento. Deve essere un valore letterale stringa e non una variabile. Non può contenere caratteri incorporati '\0' .

[in, optional] __VA_ARGS__

Fino a 99 parametri aggiuntivi per configurare o aggiungere campi all'evento. Ogni parametro deve essere una delle macro TraceLogging Wrapper, ad esempio TraceLoggingLevel, TraceLoggingKeyword o TraceLoggingValue.

Importante

ProviderId, Level e Keyword sono i mezzi principali per filtrare gli eventi. Altri tipi di filtro sono possibili, ma hanno un sovraccarico molto maggiore. Assegnare sempre un livello diverso da zero e una parola chiave a ogni evento.

Valore restituito

nessuno

Osservazioni

Ogni chiamata della macro TraceLoggingWrite si espande al codice necessario per scrivere un evento in ETW tramite l'handle del provider specificato.

TraceLoggingWrite controlla se il provider specificato è registrato. Se il provider non è registrato, TraceLoggingWrite non esegue alcuna operazione.
TraceLoggingWrite controlla se un consumer è in ascolto dell'evento, come se chiamasse TraceLoggingProviderEnabled. Se nessun consumer è in ascolto dell'evento, TraceLoggingWrite non esegue alcuna operazione.
In caso contrario, TraceLoggingWrite valuta le espressioni di runtime specificate negli argomenti, salva i risultati, inserisce i dati necessari in un evento e chiama EventWriteTransfer per inviare l'evento a ETW.

L'evento generato verrà costruito nel modo seguente:

L'ID provider, il nome del provider e il gruppo di provider dell'evento provengono dal parametro hProvider .
Il nome dell'evento proviene dal parametro eventName .
In modalità utente, l'ID attività dell'evento proviene dall'ID attività implicito del thread. In modalità kernel, l'ID attività dell'evento verrà GUID_NULL.
L'evento non avrà un ID attività correlato.
Il livello dell'evento proviene dall'argomento TraceLoggingLevel . Se non è presente alcun argomento TraceLoggingLevel, il livello dell'evento sarà 5 (WINEVENT_LEVEL_VERBOSE). Se sono presenti più argomenti TraceLoggingLevel, verrà usato l'ultimo argomento. Per abilitare il filtro degli eventi efficace, assegnare sempre un livello significativo diverso da zero a ogni evento.
La parola chiave dell'evento proviene dall'argomento TraceLoggingKeyword . Se non è presente alcun argomento TraceLoggingKeyword, la parola chiave dell'evento sarà 0 (NONE). Se sono presenti più argomenti TraceLoggingKeyword, i valori saranno OR'ed insieme. Per abilitare il filtro degli eventi efficace, assegnare sempre una parola chiave significativa diversa da zero a ogni evento.
Altri attributi di evento possono essere impostati da argomenti come TraceLoggingOpcode, TraceLoggingDescription, TraceLoggingEventTag o TraceLoggingChannel.
I campi evento possono essere raggruppati usando TraceLoggingStruct.
I campi evento vengono aggiunti da argomenti di campo come TraceLoggingValue, TraceLoggingInt32, TraceLoggingHResult, TraceLoggingString e così via. Per informazioni dettagliate, vedere Macro wrapper TraceLogging .

Ad esempio:

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.

Una chiamata di TraceLoggingWrite(hProvider, "EventName", args...) può essere considerata come l'espansione al codice come la seguente:

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);
}

Nota

Ogni macro TraceLoggingWrite controlla automaticamente TraceLoggingProviderEnabled in modo che l'evento venga scritto solo se un consumer è in ascolto di eventi dal provider. Di conseguenza, in genere non è necessario chiamare direttamente TraceLoggingProviderEnabled. Qualsiasi espressione di runtime in args... verrà valutata se e solo se l'evento è abilitato. Le espressioni di runtime non verranno valutate più di una volta.

Se si generano eventi complessi, è possibile che venga visualizzato un errore del compilatore che indica che la riga è troppo lunga o che il compilatore non è presente nello spazio dell'heap. Ciò si verifica quando la macro TraceLoggingWrite si espande a una riga più lunga di quanto possa essere supportata dal compilatore. In questo caso sarà necessario semplificare l'evento.

La macro TraceLoggingWrite utilizza una matrice di EVENT_DATA_DESCRIPTOR per trasferire i dati in ETW. Il numero massimo di descrittori accettati da ETW è 128. Poiché ogni parametro può richiedere l'uso di 0, 1 o 2 descrittori, è possibile raggiungere il limite del descrittore di dati (128) prima di raggiungere il limite di argomenti (99).

Importante

Provare a evitare eventi di grandi dimensioni. ETW è progettato principalmente per la gestione di eventi di piccole dimensioni. TraceLoggingWrite elimina automaticamente qualsiasi evento troppo grande. Le dimensioni dell'evento si basano sul totale delle intestazioni dell'evento (aggiunte dal runtime ETW), metadati (ad esempio nome del provider, nome dell'evento, nomi di campo, tipi di campo) e dati (valori di campo). Se la dimensione totale dell'evento è maggiore di 65535 o se la sessione consumer usa una dimensione del buffer inferiore alla dimensione dell'evento, l'evento non verrà registrato.

Una chiamata a TraceLoggingWrite equivale a una chiamata a TraceLoggingWriteActivity con NULL per i parametri pActivityId e pRelatedActivityId . Usare TraceLoggingWriteActivity se è necessario specificare gli ID attività per un evento.

Esempio

#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;
}

Requisiti


Client minimo supportato	Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	traceloggingprovider.h
Libreria	Advapi32.lib

Vedi anche

EventWriteTransfer

TraceLoggingWriteActivity

Macro wrapper TraceLogging

Condividi tramite