Funzione StartTraceA (evntrace.h)

  • Articolo

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

Importante

Le sessioni di traccia eventi tra processi sono una risorsa di sistema limitata. Gli sviluppatori devono evitare di avviare sessioni di traccia degli eventi nei computer dei clienti. Quando sono necessarie sessioni di traccia eventi, devono essere limitate all'ambito più piccolo possibile: usare il minor numero possibile di sessioni, usare una sessione di sola elaborazione, se possibile (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC), avviare la traccia solo quando la raccolta è specificamente necessaria per uno scenario, arrestare la traccia non appena lo scenario viene completato, limitare la quantità di memoria usata dalla sessione, e usano filtri di eventi rigorosi in modo da non raccogliere eventi non necessari.

Sintassi

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Parametri

[out] TraceHandle

Riceve l'handle per la sessione di traccia eventi per un uso successivo con API, ad esempio ControlTrace.

Non usare questo handle se la funzione ha esito negativo. Non confrontare l'handle di sessione con INVALID_HANDLE_VALUE. L'handle di sessione è 0 se l'handle non è valido.

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

Importante

Usare un nome descrittivo per la sessione in modo che la proprietà e l'utilizzo della sessione possano essere determinate dal nome della sessione. Non usare un GUID o un altro valore non deterministico o non descrittivo. Non aggiungere cifre casuali per rendere univoco il nome della sessione. Le sessioni ETW sono una risorsa limitata, quindi il componente non deve avviare più sessioni. Se la sessione del componente è già in esecuzione all'avvio del componente, il componente deve pulire la sessione orfana anziché creare una seconda sessione.

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

Per consentire al logger di essere un logger di sistema e ricevere eventi da SystemTraceProvider o da altri provider di sistema, uno dei seguenti deve essere true:

  • Il membro PropertiesLogFileMode include il flag di EVENT_TRACE_SYSTEM_LOGGER_MODE (preferito).
  • Il membro PropertiesWnode.Guid è impostato su SystemTraceControlGuid o GlobalLoggerGuid (deprecato - 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 anche di usare questo nome).

Nota

 Un logger di sistema deve impostare il membro EnableFlags della struttura EVENT_TRACE_PROPERTIES per indicare quali eventi SystemTraceProvider devono essere inclusi nella traccia.

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.

Nota

L'intestazione evntrace.h definisce StartTrace 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

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

Vedi anche

ControlTrace

EVENT_TRACE_PROPERTIES