EVENT_TRACE_PROPERTIES_V2結構 (evntrace.h)

EVENT_TRACE_PROPERTIES_V2結構包含事件追蹤會話的相關信息。 當您定義、更新或查詢會話的屬性時，您可以使用這個結構與 API，例如 StartTrace 和 ControlTrace 。

注意

這是從 EVENT_TRACE_PROPERTIES 結構延伸的第 2 版結構。 從 Windows 10 1703 版開始，支援此結構。與舊版 Windows 搭配使用時，將會忽略其他欄位 (例如 FilterDesc 和 V2Options) 。

語法

typedef struct _EVENT_TRACE_PROPERTIES_V2 {
  WNODE_HEADER             Wnode;
  ULONG                    BufferSize;
  ULONG                    MinimumBuffers;
  ULONG                    MaximumBuffers;
  ULONG                    MaximumFileSize;
  ULONG                    LogFileMode;
  ULONG                    FlushTimer;
  ULONG                    EnableFlags;
  union {
    LONG AgeLimit;
    LONG FlushThreshold;
  } DUMMYUNIONNAME;
  ULONG                    NumberOfBuffers;
  ULONG                    FreeBuffers;
  ULONG                    EventsLost;
  ULONG                    BuffersWritten;
  ULONG                    LogBuffersLost;
  ULONG                    RealTimeBuffersLost;
  HANDLE                   LoggerThreadId;
  ULONG                    LogFileNameOffset;
  ULONG                    LoggerNameOffset;
  union {
    struct {
      ULONG VersionNumber : 8;
    } DUMMYSTRUCTNAME;
    ULONG V2Control;
  } DUMMYUNIONNAME2;
  ULONG                    FilterDescCount;
  PEVENT_FILTER_DESCRIPTOR FilterDesc;
  union {
    struct {
      ULONG Wow : 1;
      ULONG QpcDeltaTracking : 1;
      ULONG LargeMdlPages : 1;
      ULONG ExcludeKernelStack : 1;
    } DUMMYSTRUCTNAME;
    ULONG64 V2Options;
  } DUMMYUNIONNAME3;
} EVENT_TRACE_PROPERTIES_V2, *PEVENT_TRACE_PROPERTIES_V2;

成員

Wnode

WNODE_HEADER結構。 您必須指定 BufferSize、 Flags 和 Guid 成員。 您可以選擇性地指定 ClientContext 成員。

重要

為了讓第 2 版欄位 (例如 FilterDesc 和 V2Options) 辨識，您必須在 中Wnode.Flags設定 WNODE_FLAG_VERSIONED_PROPERTIES 旗標。

BufferSize

配置給每個事件追蹤會話緩衝區的記憶體 KB。 緩衝區大小下限為 4 (4KB) 。 緩衝區大小上限為 16384 (16MB) 。 大部分的追蹤會話都應該使用 64KB 或更少的緩衝區大小，以避免浪費記憶體和磁碟空間。 Windows 8 之前：緩衝區大小上限為 1024 (1MB) 。

較小的緩衝區大小可減少會話記憶體使用量。 較大的緩衝區大小 (最多 64KB) 支援收集較大的事件 -- ETW 無法收集大於緩衝區大小的事件，而且無法收集大於 64KB 的事件，而不論緩衝區大小為何。 在涉及極高數據輸送量的案例中，較大的緩衝區大小可以降低 CPU 額外負荷。

• 具有小型事件的會話和低事件速率 (幾個 KB/秒) 應該使用小型緩衝區大小， (4 KB 到 16KB) 。
• 具有小型事件和中度事件速率的會話應該使用中度緩衝區大小， (16KB 到 32KB) 。
• 具有大型事件的會話或高事件速率 (數 MB/秒) 應該使用大型緩衝區大小， (64KB 到 128KB) 。
• 在極少數的情況下，應該將大量的記憶體保留給每秒數百 MB 數據的診斷追蹤，大型緩衝區大小 (256KB 到 1024KB，) 可以減少 CPU 額外負荷。

ETW 可能會在特定案例中向上調整要求的 BufferSize 。 例如，將追蹤檔案寫入磁碟時，ETW 可能會將緩衝區大小增加為磁碟實體區塊大小的倍數。

重要

BufferSize 是追蹤會話最重要的參數之一。 大型緩衝區通常會浪費記憶體和磁碟空間。 具有大型緩衝區的追蹤會話 (256KB 或更大的) ，只能用於診斷調查或測試，而不是用於生產追蹤。

提示

請勿使用 BufferSize 來控制追蹤會話的記憶體使用量。 請改為根據您的會話事件大小和事件速率選取緩衝區大小，然後使用 MinimumBuffers 和 MaximumBuffers 參數來調整會話記憶體使用量。

MinimumBuffers

保留給追蹤會話緩衝池的緩衝區數目下限。

ETW 在某些情況下可能會調整此值。

• 如果記錄模式包含 EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING 旗標，ETW 會保留至少 2 個緩衝區。
• 如果記錄模式不包含 EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING 旗標，ETW 會為每個邏輯處理器保留至少 2 個緩衝區。
• 如果此值大於 ETW 決定的限制，ETW 可能會將其縮減為限制，以避免記憶體使用量過多。

對於具有中等事件速率的檔案模式和實時追蹤，大部分的使用者都應該將 MinimumBuffer 設定為0或最小最小 (，例如4或8) ，讓ETW根據處理器數目向上調整值。 ETW 會在啟動追蹤時保留 (調整) 緩衝區數目下限。 如果緩衝區的填滿速度比可以處理得快，ETW 會配置加法緩衝區，最多可達 MaximumBuffers 所指定的數目。

針對緩衝模式 (迴圈記憶體內部) 追蹤，使用者應該根據您想要 ETW 保留給會話的記憶體總量來設定 MinimumBuffers 參數。 這通常是根據預期的事件速率和您想要追蹤涵蓋的時間量來計算。 例如，如果您預期每秒 16KB 的數據速率，而且您想要追蹤至少記錄 60 秒的數據，則需要 960KB。 假設緩衝區大小為 32KB，您會將 MinimumBuffers 設為 30 (960KB total / 32KB per buffer = 30 buffers) 。 ETW 會在啟動追蹤時保留 (調整) 緩衝區數目下限。 當所有緩衝區都填滿時，ETW 會針對新事件重複使用最舊的填滿緩衝區。 請注意，ETW 不會配置額外的緩衝區， (ETW 會忽略 buffering-mode 追蹤) 的 MaximumBuffers 。

MaximumBuffers

要配置給追蹤會話緩衝池的緩衝區數目上限。

ETW 在某些情況下可能會調整此值。

• 如果此值小於 MinimumBuffers 的調整值，ETW 可能會將其增加為等於或大於 MinimumBuffers 的適當值。
• 如果此值大於 ETW 決定的限制，ETW 可能會將其縮減為限制。

大部分的用戶都應該將 MinimumBuffers 和 MaximumBuffers 設定為相同的值，以開始微調其會話。 如果追蹤在事件速率尖峰期間卸除事件，您可能會增加 MaximumBuffers 的值。

注意

ETW 會忽略緩衝模式會話的這個欄位， (工作階段包含記錄模式 EVENT_TRACE_BUFFERING_MODE) 。 緩衝模式會話一律會在追蹤集合開始時配置 MinimumBuffer ，且永遠不會配置其他緩衝區。

MaximumFileSize

用來記錄事件、MB 或零的檔案大小上限，沒有大小限制。 一般而言，當您將 LogFileMode 設定為 EVENT_TRACE_FILE_MODE_CIRCULAR時，您會使用此成員來限制循環記錄檔的大小。 如果 LogFileMode 包含 EVENT_TRACE_FILE_MODE_PREALLOCATE或， EVENT_TRACE_FILE_MODE_CIRCULAREVENT_TRACE_FILE_MODE_NEWFILE這個成員必須設定為非零值。

如果您使用系統磁碟驅動器 (包含作業系統的磁碟驅動器) 進行記錄，則 ETW 會檢查是否有額外的 200 MB 磁碟空間，而不論您是否使用檔案大小上限參數。 因此，如果您將 100MB 指定為系統磁碟驅動器中追蹤檔案的檔案大小上限，則磁碟驅動器上必須有 300 MB 的可用空間。

LogFileMode

事件追蹤會話的記錄旗標。 您可以使用這個成員來指定是否要將事件寫入記憶體內部循環緩衝區、記錄檔或即時取用者。 您也可以使用此成員來指定其他會話特性，例如會話是私人記錄器會話。 如需可能旗標的清單，請參閱 記錄模式常數。

除非即時取用者已準備好取用事件，否則請勿指定實時記錄。 當沒有任何實時取用者時，ETW 會緩衝處理即時會話的事件。 針對會話。 沒有取用者的即時會話會浪費系統資源。 請注意，此緩衝功能有限。 如果達到限制，將會忽略新的事件，而且記錄函式會失敗。STATUS_LOG_FILE_FULL 在 Windows Vista 之前： 如果沒有即時取用者，則會捨棄事件，並繼續記錄。

如果取用者開始處理即時事件，則會先取用播放檔案中的事件。 取用播放檔案中的所有事件之後，會話就會開始報告新的事件。

FlushTimer

排清任何非空白追蹤緩衝區的頻率，以秒為單位。

• 對於檔案模式會話，排清時間下限為 1 秒。 將 FlushTimer 設定為 0 將會停用以時間為基礎的排清， (排清會在填滿緩衝區、停止會話時，或當會話明確排清) 時發生。 大部分的檔案模式追蹤都應該將 FlushTimer 設定為 0，以避免追蹤檔案中浪費的空間。 您可能會想要將定時器設定為非零值，如果追蹤可能不會關閉 (例如，如果您想要確保取得事件，即使系統當機) 也一樣。
• 對於即時會話，排清時間下限為1秒。 如果 FlushTimer 設定為 0，則會使用預設逾時 1 秒。 即時會話應該根據需要接收數據的速度來設定排清定時器。 請注意，較高的定時器值會降低追蹤的CPU額外負荷。 大部分的即時追蹤應該以 5 或 10 秒的定時器開始，並根據需求調整定時器。
• 對於緩衝處理 (記憶體內部) 會話，不會使用 FlushTimer 。 追蹤數據只會隨選排清 (，也就是透過 ControlTrace) 排清到檔案。

EnableFlags

系統記錄器會話可能會設定 EnableFlags，以指出追蹤中應該包含哪些 SystemTraceProvider 事件。

注意

EnableFlags 僅適用於系統記錄器，也就是使用記錄器模式旗標啟動的EVENT_TRACE_SYSTEM_LOGGER_MODE追蹤會話、會話名稱、KERNEL_LOGGER_NAMESystemTraceControlGuid會話 GUID 或GlobalLoggerGuid會話 GUID。

這個成員可以包含下列一或多個值。 除了您指定的事件之外，除非您指定 EVENT_TRACE_FLAG_NO_SYSCONFIG，否則記錄器也會記錄 Windows XP 上的硬體設定事件，以及 Windows Server 2003 或更新版本上的系統設定事件。

• EVENT_TRACE_FLAG_ALPC (0x00100000)

  啟用 ALPC 事件類型。

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_CSWITCH (0x00000010)

  開啟下列 Thread 事件類型：

  • CSwitch

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_DBGPRINT (0x00040000)

  讓 DbgPrint 和 DbgPrintEx 呼叫轉換成 ETW 事件。

• EVENT_TRACE_FLAG_DISK_FILE_IO (0x00000200)

  開啟下列 FileIo 事件類型， (您必須啟用EVENT_TRACE_FLAG_DISK_IO) ：

  • FileIo_Name

• EVENT_TRACE_FLAG_DISK_IO (0x00000100)

  開啟下列 DiskIo 事件類型：

  • DiskIo_TypeGroup1
  • DiskIo_TypeGroup3

• EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400)

  開啟下列 DiskIo 事件類型：

  • DiskIo_TypeGroup2

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_DISPATCHER (0x00000800)

  開啟下列 Thread 事件類型：

  • ReadyThread

  Windows 7、Windows Server 2008 R2 和更新版本支援此值。

• EVENT_TRACE_FLAG_DPC (0x00000020)

  開啟下列 PerfInfo 事件類型：

  • DPC

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_DRIVER (0x00800000)

  開啟下列 DiskIo 事件類型：

  • DriverCompleteRequest
  • DriverCompleteRequestReturn
  • DriverCompletionRoutine
  • DriverMajorFunctionCall
  • DriverMajorFunctionReturn

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_FILE_IO (0x02000000)

  開啟下列 FileIo 事件類型：

  • FileIo_OpEnd

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)

  開啟下列 FileIo 事件類型：

  • FileIo_Create
  • FileIo_DirEnum
  • FileIo_Info
  • FileIo_ReadWrite
  • FileIo_SimpleOp

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)

  開啟下列 Image 事件類型：

  • Image_Load

• EVENT_TRACE_FLAG_INTERRUPT (0x00000040)

  開啟下列 PerfInfo 事件類型：

  • ISR

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_JOB (0x00080000)

  Windows 10 支援此值

• EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS (0x00002000)

  開啟下列 PageFault_V2 事件類型：

  • PageFault_HardFault

• EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000)

  開啟下列 PageFault_V2 事件類型：

  • PageFault_TypeGroup1

• EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000)

  啟用 TcpIp 和 UdpIp 事件類型。

• EVENT_TRACE_FLAG_NO_SYSCONFIG (0x10000000)

  請勿執行系統組態取消。

  Windows 8、Windows Server 2012 及更新版本支援此值。

• EVENT_TRACE_FLAG_PROCESS (0x00000001)

  開啟下列 Process 事件類型：

  • Process_TypeGroup1

• EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)

  開啟下列 Process_V2 事件類型：

  • Process_V2_TypeGroup2

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_PROFILE (0x01000000)

  開啟下列 PerfInfo 事件類型：

  • SampledProfile

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_REGISTRY (0x00020000)

  啟用 Registry 事件類型。

• EVENT_TRACE_FLAG_SPLIT_IO (0x00200000)

  啟用 SplitIo 事件類型。

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080)

  開啟下列 PerfInfo 事件類型：

  • SysCallEnter
  • SysCallExit

  Windows Vista 和更新版本支援此值。

• EVENT_TRACE_FLAG_THREAD (0x00000002)

  開啟下列 Thread 事件類型：

  • Thread_TypeGroup1

• EVENT_TRACE_FLAG_VAMAP (0x00008000)

  啟用對應和取消對應 (排除影像檔) 事件類型。

  Windows 8、Windows Server 2012 及更新版本支援此值。

• EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000)

  開啟下列 PageFault_V2 事件類型：

  • PageFault_VirtualAlloc

  Windows 7、Windows Server 2008 R2 和更新版本支援此值。

DUMMYUNIONNAME

未使用。

DUMMYUNIONNAME.AgeLimit

未使用。

Windows 2000： 釋放未使用緩衝區之前的延遲時間，以分鐘為單位。 預設值是 15 分鐘。

DUMMYUNIONNAME.FlushThreshold

NumberOfBuffers

輸出時，為事件追蹤會話的緩衝池配置的緩衝區數目。

FreeBuffers

在輸出上，在事件追蹤會話的緩衝池中配置但未使用的緩衝區數目。

EventsLost

輸出時，未記錄的事件數目。

BuffersWritten

在輸出上，寫入的緩衝區數目。

LogBuffersLost

輸出時，無法寫入記錄檔的緩衝區數目。

RealTimeBuffersLost

在輸出上，無法即時傳遞給取用者的緩衝區數目。

LoggerThreadId

輸出時，事件追蹤會話的線程標識碼。

LogFileNameOffset

位移 (位元組) 從這個結構的配置記憶體開始到包含記錄檔名稱之 nul 終止字串的開頭。

檔名通常具有 .etl 擴展名。 路徑中的所有資料夾都必須已經存在， (ETW 將不會為您) 建立資料夾。 路徑可以是相對、絕對、本機或遠端。 路徑中的環境變數將不會展開。 用戶必須具有寫入資料夾的許可權。

記錄檔名稱限制為1,024個字元。 如果您將 LogFileMode 設定為 EVENT_TRACE_PRIVATE_LOGGER_MODE 或 EVENT_TRACE_FILE_MODE_NEWFILE，請務必保留足夠的記憶體，以包含將附加至私人記錄器會話之檔名的進程標識碼，以及使用新檔案記錄模式建立至記錄檔的序號。

例如，如果您不想將事件記錄到記錄檔 (，如果您只指定 EVENT_TRACE_REAL_TIME_MODE) ， 請將LogFileNameOffset 設定為0。 如果您只指定即時記錄，也提供具有有效記錄檔名稱的位移，ETW 會使用記錄檔名稱來建立循序記錄檔，並將事件記錄檔記錄到記錄檔，以及將事件傳送給即時取用者。 如果 LogFileMode 為 0，且您提供具有有效記錄檔名稱的位移，ETW 也會建立循序記錄檔。

如果您想要將事件記錄到記錄檔，您必須保留足夠的記憶體，此結構才能包含結構後面的記錄檔名稱和會話名稱。 記錄檔名稱必須遵循記憶體中的會話名稱。 如需範例，請參閱備註。

追蹤檔案是使用預設的安全性描述元來建立，這表示記錄檔將具有與父目錄相同的 ACL。 如果您想要存取受限制的檔案，請使用適當的 ACL 建立父目錄。

LoggerNameOffset

從結構的配置記憶體開頭到包含會話名稱之 nul 終止字串開頭的位移 (位元組) 。

重要

使用會話的描述性名稱，以便從會話名稱判斷會話的擁有權和使用方式。 請勿使用 GUID 或其他非描述性值。 請勿附加隨機數位，讓您的會話名稱是唯一的。 ETW 會話是有限的資源，因此您的元件不應該啟動多個會話。 如果您的元件會話已在元件啟動時執行，您的元件應該清除孤立的會話，而不是建立第二個會話。

會話名稱限制為1,024個字元。 會話名稱不區分大小寫。 如果另一個具有相同名稱的工作階段已在執行中，系統將不會啟動新的工作階段。

Windows 2000： 會話名稱會區分大小寫。 因此，只允許名稱不同的會話。 不過，若要減少混淆，您應該確定您的會話名稱是唯一的。

DUMMYUNIONNAME2

未使用。

DUMMYUNIONNAME2.DUMMYSTRUCTNAME

未使用。

DUMMYUNIONNAME2.DUMMYSTRUCTNAME.VersionNumber

結構的版本。 這應該設定為 “2”。

注意

只有在 Wnode.Flags 欄位包含 WNODE_FLAG_VERSIONED_PROPERTIES 旗標且基礎 ETW 運行時間辨識新的結構版本 (Windows 10 1703 版和更新版本) 時，才會辨識此字段和所有後續欄位。

DUMMYUNIONNAME2.V2Control

未使用。

FilterDescCount

FilterDesc 指向的篩選數目。 除非設定全系統的私人記錄器，否則這應該是零。

FilterDesc

支援全系統私人記錄器的 EVENT_FILTER_DESCRIPTOR 篩選類型： EVENT_FILTER_TYPE_EXECUTABLE_NAME 和 EVENT_FILTER_TYPE_PID

指向篩選數據的 EVENT_FILTER_DESCRIPTOR 結構陣列指標。 陣列中的元素數目是在 FilterDescCount 成員中指定。 特定篩選類型只能有一個篩選，如 EVENT_FILTER_DESCRIPTOR 結構的 Type 成員所指定。

除非設定全系統的私人記錄器，否則這應該是 NULL。

DUMMYUNIONNAME3

未使用。

DUMMYUNIONNAME3.DUMMYSTRUCTNAME

未使用。

DUMMYUNIONNAME3.DUMMYSTRUCTNAME.Wow

未使用。

DUMMYUNIONNAME3.DUMMYSTRUCTNAME.QpcDeltaTracking

未使用。

DUMMYUNIONNAME3.DUMMYSTRUCTNAME.LargeMdlPages

DUMMYUNIONNAME3.DUMMYSTRUCTNAME.ExcludeKernelStack

DUMMYUNIONNAME3.V2Options

未使用。

備註

此結構的行為類似於 EVENT_TRACE_PROPERTIES ，但有一些例外狀況。

結構的開頭完全定義為EVENT_TRACE_PROPERTIES，以允許此新結構與執行 Windows 版本的系統相容，然後再 Windows 10 版本 1703，且會被視為EVENT_TRACE_PROPERTIES。

使用此結構時，請務必包含在 WNODE_FLAG_VERSIONED_PROPERTIES Wnode.Flags 中，以指出這是第 2 版結構。

請注意，透過這個結構傳入 StartTrace 和 ControlTrace 的篩選，具有與 EnableTraceEx2 函式所取用之篩選相同的語意。

當您配置此結構的記憶體時，必須配置足夠的記憶體，才能在結構之後包含會話名稱和記錄檔名稱。 工作階段名稱必須位於記憶體中的記錄檔名稱之前。 您必須將記錄檔名稱複製到位移，但不會將會話名稱複製到位移。 StartTrace 函式會為您複製名稱。

設定任何成員之前，請務必將此結構的記憶體初始化為零。 例如：

typedef struct EventTracePropertyData2 {
    EVENT_TRACE_PROPERTIES_V2 Props;
    WCHAR LoggerName[128];
    WCHAR LogFileName[1024];
} EventTracePropertyData2;

EventTracePropertyData2 data = { 0 };
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID | WNODE_FLAG_VERSIONED_PROPERTIES;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData2, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData2, LoggerName);

來自提供者的事件會寫入會話的緩衝區。 當檔案或即時會話中的緩衝區已滿 (或 FlushTimer 到期) 時，會話會藉由將事件寫入記錄檔、將它們傳遞至即時取用者或兩者來排清緩衝區。 如果會話的緩衝區填滿速度比可以排清快，則會配置新的緩衝區並新增至會話的緩衝池，最多為 MaximumBuffers。 超過此限制，會話會捨棄傳入事件，直到緩衝區變成可用為止。 每個會話都會記錄捨棄的事件數目， (請參閱 EventsLost 成員) 。

ETW 不會釋放未使用的緩衝區。

Windows 2000： ETW 會根據 AgeLimit 成員值釋放未使用的緩衝區。

若要在會話執行時檢視會話統計數據，例如 EventsLost ，請呼叫 ControlTrace 函式，並將 ControlCode 參數設定為 EVENT_TRACE_CONTROL_QUERY。

規格需求

最低支援的用戶端	Windows 10 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2016 [僅限傳統型應用程式]
標頭	evntrace.h

另請參閱

StartTrace

ControlTrace

QueryAllTraces

記錄模式常數

EVENT_TRACE_PROPERTIES_V2

WNODE_HEADER