Condividi tramite


Funzione ControlTraceW (evntrace.h)

La funzione ControlTrace scarica, query, aggiornamenti o arresta la sessione di traccia eventi specificata.

Sintassi

ULONG WMIAPI ControlTraceW(
            CONTROLTRACE_ID         TraceId,
  [in]      LPCWSTR                 InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties,
  [in]      ULONG                   ControlCode
);

Parametri

TraceId

[in] InstanceName

Nome di una sessione di traccia eventi o NULL. È necessario specificare InstanceName se TraceHandle è 0.

Per specificare la sessione NT Kernel Logger, impostare InstanceName su KERNEL_LOGGER_NAME.

[in, out] Properties

Puntatore a una struttura di EVENT_TRACE_PROPERTIES inizializzata. Questa struttura deve essere zeroed-out prima di impostare tutti i campi.

Se ControlCode specifica EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERYoEVENT_TRACE_CONTROL_FLUSH, è necessario impostare solo i membri Wnode.BufferSize, Wnode.Guid, LoggerNameOffset e LogFileNameOffset della struttura EVENT_TRACE_PROPERTIES. Se la sessione è una sessione privata, è anche necessario impostare LogFileMode. È possibile usare il nome massimo della sessione (1024 caratteri) e il nome massimo del file di log (1024 caratteri) per calcolare le dimensioni del buffer e gli offset se non noti.

Se ControlCode specifica EVENT_TRACE_CONTROL_UPDATE, in input, i membri devono specificare i nuovi valori per le proprietà da aggiornare. In output, proprietà contiene le proprietà e le statistiche per la sessione di traccia eventi. È possibile aggiornare le proprietà seguenti.

  • EnableFlags: impostare questo membro su 0 per disabilitare tutti i provider di sistema. Impostare questo valore su un valore diverso da zero per specificare i provider di sistema che si desidera abilitare o mantenere abilitati. Questo può essere diverso da zero solo per i logger di sistema.

  • FlushTimer: impostare questo membro se si vuole modificare il tempo di attesa prima di scaricare i buffer. Se questo membro è 0, il membro non viene aggiornato.

  • LogFileNameOffset: impostare questo membro se si vuole passare a un altro file di log o per scaricare una traccia in modalità buffering su un nuovo file di log. Se questo membro è 0, il nome del file non viene aggiornato. Se l'offset non è zero e non si modifica il nome del file di log, la funzione restituisce un errore.

  • LogFileMode: impostare questo membro se si vuole attivare e disattivare EVENT_TRACE_REAL_TIME_MODE . Per disattivare il tempo reale, impostare questo membro su 0. Per attivare il tempo reale (creando una sessione che registra su disco e recapitando eventi in tempo reale), impostare questo membro su EVENT_TRACE_REAL_TIME_MODE e sarà OR con le modalità correnti.

  • MaximumBuffers: impostare questo membro se si vuole modificare il numero massimo di buffer usati da ETW. Se questo membro è 0, il membro non viene aggiornato.

Per le sessioni del logger privato, è possibile aggiornare solo i membri LogFileNameOffset e FlushTimer .

Se si usa una struttura di EVENT_TRACE_PROPERTIES appena inizializzata, zero-out la struttura, impostare Wnode.BufferSize, Wnode.Guid e Wnode.Flags e i valori da aggiornare.

Se si riutilizza una struttura EVENT_TRACE_PROPERTIES (ad esempio usando una struttura passata in precedenza a StartTrace o ControlTrace), assicurarsi di impostare il membro LogFileNameOffset su 0 a meno che non si modifica il nome del file di log e assicurarsi di impostare EVENT_TRACE_PROPERTIES. Wnode.Flags per WNODE_FLAG_TRACED_GUID.

A partire da Windows 10 versione 1703: Per migliorare le prestazioni negli scenari tra processi, è ora possibile passare informazioni di filtro a ControlTrace per i loggger privati a livello di sistema. È necessario usare la struttura EVENT_TRACE_PROPERTIES_V2 per includere informazioni di filtro. Per altre informazioni, vedere Configurazione e avvio di una sessione del logger privato .

[in] ControlCode

Funzione di controllo richiesta. È possibile specificare uno dei valori seguenti:

  • EVENT_TRACE_CONTROL_FLUSH: scarica i buffer attivi della sessione.

    Questa operazione può essere usata con una sessione in memoria (una sessione avviata con il flag di EVENT_TRACE_BUFFERING_MODE ) per scrivere i dati dalla traccia a un file.

    In genere non è necessario scaricare sessioni basate su file o in tempo reale perché ETW scarica automaticamente un buffer quando è pieno (ad esempio quando non ha spazio per l'evento successivo), quando la sessione di traccia scade o quando la sessione di traccia viene chiusa.

    Windows 2000: Questo valore non è supportato.

  • EVENT_TRACE_CONTROL_QUERY: recupera le proprietà e le statistiche della sessione.

  • EVENT_TRACE_CONTROL_STOP: arresta la sessione. L'handle di sessione non è più valido.

  • EVENT_TRACE_CONTROL_UPDATE: aggiorna le proprietà della sessione.

  • EVENT_TRACE_CONTROL_INCREMENT_FILE: se la sessione ha , EVENT_TRACE_FILE_MODE_NEWFILEaggiorna la sessione per passare immediatamente al file successivo anziché attendere il riempimento del file precedente. Supportato a partire da Windows 10 Ottobre 2018 Update.

  • EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME: modifica una sessione in modalità file in una sessione in tempo reale (consente il recapito in tempo reale e disabilita la scrittura di eventi nel file ETL). Supportato a partire da Windows 10 Ottobre 2020 Update.

Nota

Non è sicuro scaricare i buffer o arrestare una sessione di traccia da DllMain (potrebbe causare deadlock).

Valore restituito

Se la funzione ha esito positivo, il valore restituito è 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_BAD_LENGTH

    Una delle seguenti condizioni è vera:

    • Il membro Wnode.BufferSize di Proprietà specifica una dimensione non corretta.
    • Le proprietà non dispongono di spazio sufficiente allocato per contenere una copia del nome della sessione e del nome del file di log (se usato).
  • ERROR_INVALID_PARAMETER

    Una delle seguenti condizioni è vera:

    • Le proprietà sono NULL.
    • InstanceName e TraceHandle sono entrambi NULL.
    • InstanceName è NULL e TraceHandle non è un handle valido.
    • Il membro LogFileNameOffset di Proprietà non è valido.
    • Il membro LoggerNameOffset di Proprietà non è valido.
    • Il membro LogFileMode di Proprietà specifica una combinazione di flag non validi.
    • Il membro Wnode.Guid di Properties è SystemTraceControlGuid, ma il parametro InstanceName non KERNEL_LOGGER_NAMEè .
  • ERROR_BAD_PATHNAME

    Un'altra sessione usa già il nome del file specificato dal membro LogFileNameOffset della struttura Proprietà .

  • ERROR_MORE_DATA

    Il buffer per EVENT_TRACE_PROPERTIES è troppo piccolo per contenere tutte le informazioni per la sessione. Se non sono necessarie le informazioni sulla proprietà della sessione, è possibile ignorare questo errore. Se si riceve questo errore durante l'arresto della sessione, ETW avrà già arrestato la sessione prima di generare questo errore.

  • ERROR_ACCESS_DENIED

    Solo gli utenti che eseguono con privilegi amministrativi elevati, gli utenti nel gruppo Utenti log prestazioni e i servizi in esecuzione come LocalSystem, LocalService, NetworkService possono controllare le sessioni di traccia degli eventi. Per concedere a un utente limitato la possibilità di controllare le sessioni di traccia, aggiungerle al gruppo Utenti log prestazioni. Solo gli utenti con privilegi e servizi amministrativi in esecuzione come LocalSystem possono controllare una sessione NT Kernel Logger.

    Windows XP e Windows 2000: Chiunque può controllare una sessione di traccia.

  • ERROR_WMI_INSTANCE_NOT_FOUND

    La sessione specificata non è in esecuzione.

  • ERROR_ACTIVE_CONNECTIONS

    Quando viene restituito da una chiamata EVENT_TRACE_CONTROL_STOP, questa indica che la sessione è già in fase di arresto.

Commenti

I controller di traccia eventi chiamano questa funzione.

Questa funzione sostituisce le funzioni FlushTrace, QueryTrace, StopTrace e UpdateTrace .

Nota

L'intestazione evntrace.h definisce ControlTrace come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

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 Sechost.lib in Windows 8.1 e Windows Server 2012 R2; Advapi32.lib in Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP
DLL Sechost.dll in Windows 8.1 e Windows Server 2012; Advapi32.dll in Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista e Windows XP

Vedi anche

EVENT_TRACE_PROPERTIES

QueryAllTraces

StartTrace