Macro TraceLoggingWrite (traceloggingprovider.h)

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.

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

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).

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

Vedi anche

EventWriteTransfer

TraceLoggingWriteActivity

Macro wrapper TraceLogging