Funzione StartTraceA (evntrace.h)

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

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.

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

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.

Requisiti

Vedi anche

ControlTrace

EVENT_TRACE_PROPERTIES