Funzione EnableTrace (evntrace.h)

Articolo
06/12/2024

Un controller di sessione di traccia chiama EnableTrace 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 EnableTrace(
  [in] ULONG           Enable,
  [in] ULONG           EnableFlag,
  [in] ULONG           EnableLevel,
  [in] LPCGUID         ControlGuid,
       CONTROLTRACE_ID TraceId
);

Parametri

[in] Enable

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] EnableFlag

Maschera di bit a 32 bit di parole chiave 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 il critera EnableLevel .

Nota

I provider basati su EventRegister supportano parole chiave a 64 bit. Usare EnableTraceEx2 per abilitare i provider usando una maschera MatchAnyKeyword a 64 bit.

[in] EnableLevel

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

Questo valore deve essere compreso nell'intervallo compreso tra 1 e 255. 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] ControlGuid

GUID del controllo (ID provider) del provider di eventi che si desidera abilitare o disabilitare.

TraceId

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:
- ControlGuid è NULL.
- TraceHandle è NULL.
ERROR_INVALID_FUNCTION

Non è possibile modificare i flag di abilitazione e il livello quando il provider non è registrato.
ERROR_WMI_GUID_NOT_FOUND

Il provider non è registrato. Si verifica quando KB307331 o Windows 2000 Service Pack 4 è installato e il provider non è registrato. Per evitare questo errore, il provider deve prima essere 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 Users gruppo e i servizi in esecuzione come LocalSystem, LocalServiceo NetworkService possono 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 al Performance Log Users gruppo 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.

Le due chiamate di funzione seguenti sono equivalenti:

// Obsolete:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // 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 2000 Professional [app desktop \| App UWP]
Server minimo supportato	Windows 2000 Server [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	evntrace.h
Libreria	Advapi32.lib
DLL	Advapi32.dll

Vedi anche

StartTrace

EnableTraceEx2

Condividi tramite