Funzione StartTraceW (evntrace.h)

La funzione StartTrace registra e avvia una sessione di traccia eventi.

Sintassi

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

Parametri

TraceId

[in] InstanceName

Stringa con terminazione Null contenente il nome della sessione di traccia eventi. Il nome della sessione è limitato a 1.024 caratteri, non fa distinzione tra maiuscole e minuscole e deve essere univoco.

Questa funzione copia il nome della sessione fornito all'offset a cui punta il membro LoggerNameOffset di Proprietà .

[in, out] Properties

Puntatore a una struttura EVENT_TRACE_PROPERTIES che specifica il comportamento della sessione. Di seguito sono riportati i membri chiave della struttura da impostare:

• Wnode.BufferSize
• Wnode.Guid
• Wnode.ClientContext
• Wnode.Flags
• LogFileMode
• LogFileNameOffset
• LoggerNameOffset

A seconda del tipo di file di log che si sceglie di creare, potrebbe essere necessario specificare anche un valore per MaximumFileSize. Per altre informazioni sull'impostazione del parametro Proprietà e sul comportamento della sessione, vedere la sezione Osservazioni.

A partire da Windows 10, versione 1703: Per prestazioni migliori negli scenari tra processi, è ora possibile passare il filtro a StartTrace quando si avviano logger privati a livello di sistema. Sarà necessario passare la nuova struttura EVENT_TRACE_PROPERTIES_V2 per includere le informazioni di filtro. Per altri dettagli, vedere Configurazione e avvio di una sessione di logger privato .

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_BAD_LENGTH

  Una delle seguenti condizioni è vera:

  • Il membro Wnode.BufferSize di Properties specifica una dimensione non corretta.
  • Le proprietà non hanno spazio sufficiente allocato per contenere una copia di InstanceName.

• ERROR_INVALID_PARAMETER

  Una delle seguenti condizioni è vera:

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

• ERROR_ALREADY_EXISTS

  È già in esecuzione una sessione con lo stesso nome o GUID.

• ERROR_BAD_PATHNAME

  È possibile ricevere questo errore per uno dei motivi seguenti:

  • Un'altra sessione usa già il nome file specificato dal membro LogFileNameOffset della struttura Properties .
  • Sia LogFileMode che LogFileNameOffset sono zero.

• ERROR_DISK_FULL

  Spazio disponibile insufficiente nell'unità per il file di log. Ciò si verifica se:

  • MaximumFileSize è diverso da zero e non sono disponibili byte MaximumFileSize per il file di log
  • l'unità è un'unità di sistema e non è disponibile un ulteriore 200 MB
  • MaximumFileSize è zero e non sono disponibili ulteriori 200 MB

  Scegliere un'unità con più spazio o ridurre le dimensioni specificate in MaximumFileSize (se usato).

• ERROR_ACCESS_DENIED

  Solo gli utenti con privilegi amministrativi, gli utenti nel gruppo Performance Log Users e i servizi in esecuzione come LocalSystem, LocalService, NetworkService possono controllare le sessioni di traccia degli eventi. Per concedere a un utente con restrizioni la possibilità di controllare le sessioni di traccia, aggiungerle al gruppo Performance Log Users . Solo gli utenti con privilegi amministrativi e servizi in esecuzione come LocalSystem possono controllare una sessione nt kernel logger.

  Se l'utente è membro del gruppo Performance Log Users, potrebbe non avere l'autorizzazione per creare il file di log nella cartella specificata.

• ERROR_NO_SYSTEM_RESOURCES

  Una delle seguenti condizioni è vera:

  • La sessione di registrazione usa il flag EVENT_TRACE_SYSTEM_LOGGER_MODE e viene raggiunto il numero massimo di logger di sistema (8).

  • È stato raggiunto il numero massimo di sessioni di registrazione nel sistema. Non è possibile creare nuovi logger fino a quando non viene arrestata una sessione di registrazione. Nella maggior parte dei sistemi, il numero massimo di sessioni di registrazione è 64.

    È possibile modificare il numero massimo di sessioni di registrazione per un sistema modificando la chiave REG_DWORD in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers. I valori consentiti sono compresi tra 32 e 256 inclusi. È necessario un riavvio per rendere effettiva qualsiasi modifica.

    Si noti che i logger usano le risorse di sistema. L'aumento del numero di logger nel sistema comporta un costo di prestazioni se tali slot vengono riempiti. Questo limite esiste per evitare un uso eccessivo delle risorse di sistema.

    Importante

    Il limite deve essere modificato manualmente solo da un amministratore di sistema per abilitare scenari specifici. L'impostazione EtwMaxLoggers non deve essere modificata automaticamente da un programma o da un driver.

    Prima di Windows 10, versione 1709, si tratta di un limite fisso di 64 logger per logger non privati.

Commenti

I controller di traccia eventi chiamano questa funzione.

La sessione rimane attiva finché la sessione non viene arrestata, il computer viene riavviato, si verifica un errore di I/O o o la dimensione massima del file per i log non circolari. Per arrestare una sessione di traccia eventi, chiamare la funzione ControlTrace e impostare il parametro ControlCode su EVENT_TRACE_CONTROL_STOP.

Non è possibile avviare più di una sessione con lo stesso GUID di sessione (come specificato da Properties.Wnode.Guid). Nella maggior parte dei casi, si imposterà Properties.Wnode.Guid su all-zero (ad esempio , GUID_NULL) per consentire al sistema ETW di generare un nuovo GUID per la sessione.

Per specificare una sessione del logger privato, impostare il membro Wnode.Guid di Proprietà sul GUID del controllo del provider, non sul GUID del controllo della sessione del logger privato. Il provider deve aver registrato il GUID prima di chiamare StartTrace.

Questa funzione non viene usata per avviare una sessione logger globale (deprecata). Per informazioni dettagliate sull'avvio di una sessione di logger globale, vedere Configurazione e avvio della sessione globale del logger.

Logger di sistema

Affinché il logger sia un logger di sistema e riceva eventi da SystemTraceProvider o da altri provider di sistema, è necessario che venga soddisfatta una delle condizioni seguenti:

• Il membro PropertiesLogFileMode include il flag EVENT_TRACE_SYSTEM_LOGGER_MODE (preferito).
• Il membro PropertiesWnode.Guid è impostato su SystemTraceControlGuid o GlobalLoggerGuid (non deve essere usato per il nuovo codice perché sarà in conflitto con altri componenti che tentano anche di usare questi GUID).
• InstanceName è impostato su KERNEL_LOGGER_NAME (deprecato: non deve essere usato per il nuovo codice perché sarà in conflitto con altri componenti che tentano di usare questo nome).

Poiché i loggger di sistema ricevono eventi kernel speciali, sono soggetti a restrizioni aggiuntive:

• Non possono essere presenti più di 8 loggger di sistema attivi nello stesso sistema.
• I loggger di sistema non possono essere creati all'interno di un contenitore di Windows Server.
• I loggger di sistema non possono usare il flag di EVENT_TRACE_USE_PAGED_MEMORY .
• Prima di Windows 10, versione 1703, non è possibile usare più di 2 tipi di orologio distinti contemporaneamente da tutti i loggger di sistema. Ad esempio, se un logger di sistema attivo usa il tipo di orologio "Contatore ciclo CPU" e un altro logger di sistema attivo usa il tipo di orologio "Contatore prestazioni query", quindi qualsiasi tentativo di avviare un logger di sistema usando il tipo di orologio "Tempo di sistema" avrà esito negativo perché richiederebbe l'attivazione di un terzo tipo di orologio. A causa di questa limitazione, Microsoft consiglia vivamente che i loggger di sistema non usino il tipo di orologio "Ora di sistema".
• A partire da Windows 10 versione 1703, la restrizione del tipo di orologio è stata rimossa. Tutti e tre i tipi di orologio possono ora essere usati simultaneamente dai loggger di sistema.

Per specificare una sessione NT Kernel Logger (deprecata), impostare InstanceName su KERNEL_LOGGER_NAME e il membro Wnode.Guid di Proprietà su SystemTraceControlGuid. Se non si specifica il GUID come SystemTraceControlGuid, ETW eseguirà l'override del valore GUID e lo imposta su SystemTraceControlGuid.

Esempio

Per un esempio che usa StartTrace, vedere Configurazione e avvio di una sessione di traccia eventi.

Requisiti

Vedi anche

ControlTrace

EVENT_TRACE_PROPERTIES