Macro TraceLoggingWriteActivity (traceloggingprovider.h)

  • Articolo

Genera un evento TraceLogging con ID attività specificati.

Sintassi

void TraceLoggingWriteActivity(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  pActivityId,
  [in, optional]  pRelatedActivityId,
  [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ò avere caratteri incorporati '\0' .

[in, optional] pActivityId

ID attività per l'evento o NULL per usare il valore predefinito.

[in, optional] pRelatedActivityId

ID attività correlato per l'evento o NULL per nessun ID attività correlato.

[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 and Keyword sono i mezzi principali per filtrare gli eventi. Altri tipi di filtro sono possibili, ma hanno un sovraccarico molto più elevato. Assegnare sempre un livello e una parola chiave non zero a ogni evento.

Valore restituito

nessuno

Osservazioni

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

  • TraceLoggingWriteActivity verifica se il provider specificato è registrato. Se il provider non è registrato, TraceLoggingWriteActivity non fa nulla.
  • TraceLoggingWriteActivity verifica se qualsiasi consumer è in ascolto dell'evento, come se chiamando TraceLoggingProviderEnabled. Se nessun consumer è in ascolto dell'evento, TraceLoggingWriteActivity non fa nulla.
  • In caso contrario, TraceLoggingWriteActivity 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 come segue:

  • L'ID provider dell'evento, il nome del provider e il gruppo di provider provengono dal parametro hProvider .
  • Il nome dell'evento proviene dal parametro eventName .
  • L'ID attività dell'evento proviene dal parametro pActivityId . Se pActivityId è NULL, gli eventi in modalità utente useranno l'ID attività implicita del thread e gli eventi in modalità kernel useranno GUID_NULL.
  • L'ID attività correlato dell'evento proviene dal parametro pRelatedActivityId . Se pRelatedActivityId è 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 è presente più di un argomento TraceLoggingLevel, verrà usato l'ultimo argomento. Per abilitare il filtro degli eventi efficace, assegnare sempre un livello non zero significativo 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 non zero significativa 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:

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.

Una chiamata di TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, args...) può essere considerata come espandere il codice come il seguente:

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

Nota

Ogni macro TraceLoggingWriteActivity controlla automaticamente TraceLoggingProviderEnabled in modo che l'evento venga scritto solo se un consumer sta ascoltando gli eventi dal provider. Di conseguenza, in genere non è necessario chiamare direttamente TraceLoggingProviderEnabled. Tutte le espressioni di runtime in args... verranno valutate 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 è disponibile nello spazio heap. Ciò si verifica quando la macro TraceLoggingWriteActivity si espande a una riga più lunga di quanto possa essere supportata dal compilatore. In questo caso è necessario semplificare l'evento.

La macro TraceLoggingWriteActivity usa 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 dati (128) prima di raggiungere il limite di argomento (99).

Importante

Provare a evitare eventi di grandi dimensioni. ETW è progettato principalmente per la gestione di piccoli eventi. TraceLoggingWriteActivity 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 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 è uguale a una chiamata a TraceLoggingWriteActivity con NULL per i parametri pActivityId e pRelatedActivityId. Usare TraceLoggingWriteActivity se è necessario specificare gli ID attività per un evento.

Per informazioni sulla semantica dei parametri ActivityId e RelatedActivityId, vedere EventWriteTransfer.

Per informazioni sulla scrittura di attività in ETW, vedere EventActivityIdControl .

Vedere TraceLoggingActivity per le classi C++ che consentono di gestire le attività TraceLogging ETW.

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

EventActivityIdControl

EventWriteTransfer

TraceLoggingActivity

TraceLoggingWrite

Macro Wrapper traceLogging