Condividi tramite

Funzione EnableTraceEx (evntrace.h)

  • Articolo

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

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

Vedi anche

StartTrace

EnableTraceEx2