Funzione EnableTraceEx (evntrace.h)
Un controller di sessione di traccia chiama EnableTraceEx per configurare il modo in cui un provider di eventi ETW registra gli eventi in una sessione di traccia.
questa funzione è obsoleta. La funzione EnableTraceEx2 sostituisce questa funzione.
Sintassi
ULONG WMIAPI EnableTraceEx(
[in] LPCGUID ProviderId,
[in, optional] LPCGUID SourceId,
CONTROLTRACE_ID TraceId,
[in] ULONG IsEnabled,
[in] UCHAR Level,
[in] ULONGLONG MatchAnyKeyword,
[in] ULONGLONG MatchAllKeyword,
[in] ULONG EnableProperty,
[in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);
Parametri
[in] ProviderId
ID provider (GUID di controllo) del provider di eventi da configurare.
[in, optional] SourceId
GUID che può identificare in modo univoco l'origine di questa richiesta di configurazione o NULL se non è necessaria alcuna identità di origine (equivalente all'impostazione di SourceId su &GUID_NULL). Se specificato, questo valore viene usato come parametro SourceId quando si richiama l'oggetto EnableCallback del provider.
Nota
Non esiste sempre un mapping diretto tra una chiamata a EnableTrace e una chiamata corrispondente all'EnableCallback del provider. Ad esempio, se EnableTrace viene chiamato per un provider che non è ancora stato registrato, la chiamata a EnableCallback verrà posticipata fino a quando non si verifica la registrazione e, se viene arrestata una sessione consumer di traccia, ETW richiamerà EnableCallback anche se non era presente alcuna chiamata corrispondente a EnableTrace. In questi casi, EnableTrace verrà richiamato con SourceId impostato su GUID_NULL.
TraceId
[in] IsEnabled
Impostare su 1 per abilitare la ricezione di eventi dal provider o per modificare le impostazioni usate durante la ricezione di eventi dal provider, ad esempio per modificare il livello e le parole chiave. Impostare su 0 per disabilitare la ricezione di eventi dal provider.
[in] Level
Valore che indica il livello massimo di eventi che il provider deve scrivere. Il provider scrive in genere un evento se il livello dell'evento è minore o uguale a questo valore, oltre a soddisfare i criteri MatchAnyKeyword e MatchAllKeyword .
Microsoft definisce la semantica dei livelli 1-5, come illustrato di seguito. I valori inferiori indicano eventi più gravi. Ogni valore di EnableLevel abilita il livello specificato e tutti i livelli più gravi. Ad esempio, se si specifica TRACE_LEVEL_WARNING, il consumer riceverà avvisi, errori ed eventi critici.
| Valore | Significato |
|---|---|
| TRACE_LEVEL_CRITICAL (1) | Eventi di chiusura o chiusura anomali |
| TRACE_LEVEL_ERROR (2) | Eventi di errore gravi |
| TRACE_LEVEL_WARNING (3) | Eventi di avviso, ad esempio errori di allocazione |
| TRACE_LEVEL_INFORMATION (4) | Eventi informativi non di errore |
| TRACE_LEVEL_VERBOSE (5) | Eventi di diagnostica dettagliati |
Le TRACE_LEVEL costanti sono definite in evntrace.h. Le costanti equivalenti WINMETA_LEVEL sono definite in winmeta.h.
[in] MatchAnyKeyword
Maschera di parole chiave a 64 bit che determinano le categorie di eventi che si desidera che il provider scriva. Il provider scrive in genere un evento se i bit della parola chiave dell'evento corrispondono a uno qualsiasi dei bit impostati in questo valore o se l'evento non ha bit di parole chiave impostati, oltre a soddisfare i criteri Level e MatchAllKeyword .
[in] MatchAllKeyword
Maschera di parole chiave a 64 bit che limita gli eventi che si desidera che il provider scriva. Il provider scrive in genere un evento se i bit della parola chiave dell'evento corrispondono a tutti i bit impostati in questo valore o se l'evento non ha bit di parole chiave impostati, oltre a soddisfare i criteri Level e MatchAnyKeyword .
Questo valore viene spesso impostato su 0.
[in] EnableProperty
Flag che specificano comportamenti speciali che il runtime ETW deve abilitare durante la raccolta di eventi da questo provider. Per abilitare comportamenti speciali, specificare uno o più flag seguenti. In caso contrario, impostare EnableProperty su 0.
Nota
Diversi di questi flag indicano che ETW deve includere informazioni aggiuntive in ogni evento. I dati sono scritti nella sezione dell'elemento di dati esteso dell'evento.
| Valore | Significato |
|---|---|
| EVENT_ENABLE_PROPERTY_SID | Includere l'identificatore di sicurezza (SID) dell'utente nei dati estesi. |
| EVENT_ENABLE_PROPERTY_TS_ID | Includere l'identificatore di sessione del terminale nei dati estesi. |
| EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 | La sessione di traccia non deve registrare gli eventi con una parola chiave pari a 0. |
[in, optional] EnableFilterDesc
Struttura EVENT_FILTER_DESCRIPTOR che punta ai dati del filtro. Il provider usa questa opzione per filtrare i dati per impedire che gli eventi che non corrispondono ai criteri di filtro vengano scritti nella sessione. Il provider determina il layout dei dati e la modalità di applicazione del filtro ai dati dell'evento. Una sessione può passare un solo filtro al provider.
Una sessione può chiamare la funzione TdhEnumerateProviderFilters per cercare i filtri per i quali un provider ha registrato il supporto.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore di sistema. Di seguito sono riportati alcuni errori comuni e le relative cause.
ERROR_INVALID_PARAMETER
Una delle seguenti condizioni è vera:
- ProviderId è NULL.
- TraceHandle è NULL.
ERROR_INVALID_FUNCTION
Non è possibile aggiornare il livello quando il provider non è registrato.
ERROR_NO_SYSTEM_RESOURCES
È stato superato il numero di sessioni di traccia che possono abilitare il provider.
ERROR_ACCESS_DENIED
Solo gli utenti con privilegi amministrativi, gli utenti nel
Performance Log Usersgruppo e i servizi in esecuzione comeLocalSystem,LocalServiceoNetworkServicepossono abilitare i provider di eventi a una sessione tra processi. Per concedere a un utente con restrizioni la possibilità di abilitare un provider di eventi, aggiungerli alPerformance Log Usersgruppo o vedere EventAccessControl.Windows XP e Windows 2000: Chiunque può abilitare un provider di eventi.
Commenti
I controller di traccia eventi chiamano questa funzione per configurare i provider di eventi che scrivono eventi nella sessione. Ad esempio, un controller potrebbe chiamare questa funzione per iniziare a raccogliere eventi da un provider, per modificare il livello o le parole chiave degli eventi raccolti da un provider o per interrompere la raccolta di eventi da un provider.
questa funzione è obsoleta. Per altre funzionalità, il nuovo codice deve usare EnableTraceEx2.
Nella maggior parte dei casi, una chiamata a EnableTraceEx può essere convertita in EnableTraceEx2 come indicato di seguito:
// Obsolete:
Status =
EnableTraceEx(
ProviderId,
NULL, // SourceId
TraceHandle,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
0, // EnableProperty
NULL); // EnableFilterDesc
// Updated equivalent code:
Status = EnableTraceEx2(
TraceHandle,
ProviderId,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
0, // Timeout
NULL); // EnableParameters
In scenari più complessi, una chiamata a EnableTraceEx può essere convertita in EnableTraceEx2 come indicato di seguito:
// Obsolete:
Status =
EnableTraceEx(
ProviderId,
SourceId,
TraceHandle,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
EnableProperty,
EnableFilterDesc);
// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
ENABLE_TRACE_PARAMETERS_VERSION_2,
EnableProperty,
0, // ControlFlags
SourceId ? *SourceId : GUID_NULL,
EnableFilterDesc,
EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
TraceHandle,
ProviderId,
IsEnabled,
Level,
MatchAnyKeyword,
MatchAllKeyword,
0, // Timeout
&EnableParameters);
Per altri dettagli sulla semantica della configurazione dei provider per una sessione, vedere la documentazione per EnableTraceEx2.
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 | evntrace.h |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |