Funzione EventActivityIdControl (evntprov.h)

  • Articolo

Crea, query e imposta gli identificatori di attività da usare negli eventi ETW.

Sintassi

ULONG EVNTAPI EventActivityIdControl(
  [in]      ULONG  ControlCode,
  [in, out] LPGUID ActivityId
);

Parametri

[in] ControlCode

Codice di controllo che specifica l'operazione da eseguire.

  • EVENT_ACTIVITY_CTRL_GET_ID

    Imposta il parametro ActivityId sul valore dell'ID attività del thread corrente.

  • EVENT_ACTIVITY_CTRL_SET_ID

    Imposta l'ID attività del thread corrente sul valore del parametro ActivityId .

  • EVENT_ACTIVITY_CTRL_CREATE_ID

    Imposta il parametro ActivityId sul valore di un ID attività univoco locale appena generato.

  • EVENT_ACTIVITY_CTRL_GET_SET_ID

    Scambia i valori del parametro ActivityId e l'ID attività del thread corrente. Salva il valore dell'ID attività del thread corrente, quindi imposta l'ID attività del thread corrente sul valore del parametro ActivityId , quindi imposta il parametro ActivityId sul valore salvato.

  • EVENT_ACTIVITY_CTRL_CREATE_SET_ID

    Imposta il parametro ActivityId sul valore dell'ID attività del thread corrente, quindi imposta l'ID attività del thread corrente sul valore di un ID attività univoco locale appena generato.

[in, out] ActivityId

Puntatore a un buffer contenente un ID attività a 128 bit. Questo buffer può essere letto da e/o scritto a, a seconda del valore del parametro ControlCode .

Valore restituito

Restituisce ERROR_SUCCESS se riuscito.

Commenti

Gli eventi ETW scritti usando una delle API EventWrite conterrà un campo "ID attività" a 128 bit e può contenere facoltativamente un campo "ID attività correlato" a 128 bit. Gli strumenti di elaborazione delle tracce possono usare i valori di questi campi per organizzare gli eventi in gruppi denominati attività.

  • Tutti gli eventi con un ID attività pari a zero (ad esempio GUID_NULL) si presuppone che non faccia parte di alcuna attività.
  • Si presuppone che tutti gli eventi con un ID attività non zero specifico facciano parte della stessa attività.
  • Per indicare l'inizio dell'attività, il provider deve impostare Opcode su WINEVENT_OPCODE_START per il primo evento con un ID attività non zero specifico (l'evento start ). Se l'attività è annidata logicamente all'interno di un'altra attività, il provider deve impostare il campo ID attività correlato all'evento iniziale sull'ID dell'attività padre.
  • Per indicare la fine dell'attività, il provider deve impostare Opcode su WINEVENT_OPCODE_STOP per l'ultimo evento con un ID attività diverso da zero specifico (evento di arresto ).

Per gli ID attività utili, gli ID attività appena generati devono essere univoci in locale, ad esempio lo stesso ID non deve essere generato due volte all'interno della traccia.

È possibile creare ID attività usando EventActivityIdControl, che genera ID univoci in locale che devono essere univoci in tutti i processi nel sistema locale fino al riavvio del sistema. È anche possibile usare un GUID (identificatore univoco globale) come ID attività. È possibile creare un GUID usando un'API come UuidCreate.

I thread in modalità utente hanno un valore ID attività a 128 bit locale del thread (ID attività del thread). L'ID attività del thread viene inizializzato su 0 (ad esempio GUID_NULL) quando viene creato il thread. L'ID attività del thread può essere letto o aggiornato usando EventActivityIdControl. L'ID attività del thread verrà usato come ID attività per tutti gli eventi scritti da EventWrite e per tutti gli eventi scritti da EventWriteTransfer o EventWriteEx in cui il parametro ActivityId è NULL.

Importante

Una funzione che modifica l'ID attività di un thread deve essere attenta a ripristinare l'ID attività originale prima di uscire. In caso contrario, le modifiche apportate all'ID attività del thread interferiranno con le attività dei componenti che chiamano la funzione.

Uso di un ID attività specificato in modo esplicito

Nei casi in cui le attività non sono limitate a un singolo thread o dove si vuole evitare la possibilità di interferenza da altri componenti sovrascrivendo l'ID attività del thread, è possibile specificare in modo esplicito le attività dell'evento tramite il campo ActivityId di EventWriteTransfer o EventWriteEx anziché usare l'ID attività thread automatico.

Se si usano manifesti e compilatore messaggi per scrivere eventi, le macro generate dall'ID MC.exe -um attività del thread vengono usate mentre le macro generate da MC.exe -km supportano un parametro ID attività. In origine, le macro funzionano solo in modalità utente e le -um-km macro funzionano solo in modalità kernel, quindi il codice in modalità utente può usare solo l'ID attività del thread corrente. Tuttavia, a partire da MC.exe versione 10.0.17741, le macro generate da MC.exe -km possono essere usate sia per la modalità utente che per la modalità kernel, in modo MC.exe -km da poter generare macro che accettano un parametro ID attività. Il codice generato da MC non supporta l'impostazione dell'ID attività correlata di un evento.

Se si usa TraceLoggingProvider.h per scrivere eventi, la macro TraceLoggingWrite usa l'ID attività del thread, mentre TraceLoggingWriteActivity accetta parametri per ID attività e ID attività correlati. In alternativa, è possibile usare le classi C++ in TraceLoggingActivity.h per le attività TraceLogging .

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [app desktop | App UWP]
Server minimo supportato Windows Server 2008 [app desktop | App UWP]
Piattaforma di destinazione Windows
Intestazione evntprov.h
Libreria Advapi32.lib
DLL Advapi32.dll

Vedi anche

EventWriteTransfer