Condividi tramite

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 eventi nei computer clienti. Quando sono necessarie sessioni di traccia eventi, devono essere limitate all'ambito più piccolo possibile: usare le più piccole sessioni possibili, 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 viene completato lo scenario, limitare la quantità di memoria usata dalla sessione, e usare filtri eventi rigorosi in modo da non raccogliere eventi non necessari.

Sintassi

ULONG WMIAPI StartTraceA(
            CONTROLTRACE_ID         *TraceId,
  [in]      LPCSTR                  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, è senza 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 in modo che il componente non inizi 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 specificato 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 migliorare le prestazioni negli scenari tra processi, è ora possibile passare il filtro in StartTrace quando si avviano registri privati a livello di sistema. Sarà necessario passare la nuova struttura EVENT_TRACE_PROPERTIES_V2 per includere informazioni di filtro. Per altre informazioni, vedere Configurazione e avvio di una sessione del logger privato .

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 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 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 è SystemTraceControlGuid, ma il parametro InstanceName non è KERNEL_LOGGER_NAME.

  • ERROR_ALREADY_EXISTS

    Una sessione con lo stesso nome o GUID è già in esecuzione.

  • ERROR_BAD_PATHNAME

    È possibile ricevere questo errore per uno dei motivi seguenti:

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

  • ERROR_DISK_FULL

    Non è disponibile spazio sufficiente sull'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 è disponibile un numero aggiuntivo di 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 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.

    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 il numero massimo di loggers di sistema (8) è stato raggiunto.

    • È stato raggiunto il numero massimo di sessioni di registrazione nel sistema. Non è possibile creare nuovi loggger fino a quando non è stata 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 di REG_DWORD in HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers. I valori consentiti sono compresi tra 32 e 256. È necessario un riavvio per qualsiasi modifica da apportare.

      Si noti che Loggers usa le risorse di sistema. L'aumento del numero di logger nel sistema avrà un costo di prestazioni se tali slot vengono riempiti. Questo limite esiste per evitare un utilizzo 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 loggers per i loggger 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 per i log non circolari viene raggiunta la dimensione massima del file. 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 della sessione (come specificato da Properties.Wnode.Guid). Nella maggior parte dei casi, si imposta 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 GUID di Wnode.Guid membro di Proprietà sul GUID del controllo del provider, non il GUID 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 di logger globale (deprecata). Per informazioni dettagliate sull'avvio di una sessione di logger globale, vedere Configurazione e avvio della sessione globale del logger.

Loggers 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 logger di sistema ricevono eventi speciali del kernel, sono soggetti a restrizioni aggiuntive:

  • Non possono essere presenti più di 8 logger di sistema attivi nello stesso sistema.
  • I logger di sistema non possono essere creati all'interno di un contenitore di Windows Server.
  • I logger di sistema non possono usare il flag EVENT_TRACE_USE_PAGED_MEMORY .
  • Prima di Windows 10, versione 1703, non più di 2 tipi di orologio distinti possono essere usati contemporaneamente da qualsiasi logger 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", qualsiasi tentativo di avviare un logger di sistema usando il tipo di orologio "Ora 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 logger 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 contemporaneamente dai logger di sistema.

Per specificare una sessione del Logger del kernel NT (deprecata), impostare InstanceName su KERNEL_LOGGER_NAME e il membro Wnode.Guid di Properties su SystemTraceControlGuid. Se non si specifica il GUID come SystemTraceControlGuid, ETW sostituirà il valore GUID e lo imposterà 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

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