EVENT_TRACE_PROPERTIES 結構 (evntrace.h)

EVENT_TRACE_PROPERTIES結構包含事件追蹤會話的相關信息。 您可以在定義、更新或查詢會話的屬性時，搭配 StartTrace 和 ControlTrace 等 API 使用此結構。

注意

這是第 1 版結構。 EVENT_TRACE_PROPERTIES_V2 (支援其他選項，例如 FilterDesc 和 V2Options) 。

語法

typedef struct _EVENT_TRACE_PROPERTIES {
  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;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;

成員

Wnode

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

BufferSize

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

較小的緩衝區大小可減少會話記憶體使用量，並可協助減少記錄檔大小。 較大的緩衝區大小支援收集較大的事件，因為 ETW 不會跨緩衝區界限分散事件，因此無法收集大於緩衝區大小的事件。 在涉及極高數據輸送量的案例中，較大的緩衝區大小也可以降低 CPU 額外負荷。

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

注意

不論緩衝區大小為何，ETW 都無法收集大於 64KB 的事件。

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 可能會減少到限制，以避免使用過多的記憶體。

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

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

MaximumBuffers

要為追蹤會話的緩衝池配置的最大緩衝區數目。

ETW 可能會在某些案例中調整此值。

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

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

如果事件是由以高 IRQL 執行的驅動程式產生，ETW 就無法配置隨選緩衝區。 如果您的追蹤會話需要記錄來自高 IRQL 核心模式提供者的事件，可能需要使用較高的 MinimumBuffers 值來強制預先配置緩衝區。

注意

ETW 會忽略緩衝模式會話的 MaximumBuffers ， (包含記錄模式 EVENT_TRACE_BUFFERING_MODE 的會話) 。 緩衝模式會話一律會在追蹤集合開始時配置 MinimumBuffers ，且永遠不會配置其他緩衝區。

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 之前： 如果沒有即時取用者，則會捨棄事件並繼續記錄。

除非即時取用者會取用事件，否則請勿啟動實時記錄會話。 沒有取用者的即時會話會浪費系統資源， (CPU、記憶體和磁碟空間來緩衝事件) 。

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

FlushTimer

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

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

EnableFlags

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

注意

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

這個成員可以包含下列一或多個值。 除了您指定的事件之外，除非您指定 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)

  啟用要轉換成 ETW 事件的 DbgPrint 和 DbgPrintEx 呼叫。

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

  啟用 登錄 事件類型。

• 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： 會話名稱會區分大小寫。 因此，只允許名稱不同的會話。 不過，若要減少混淆，您應該確定您的會話名稱是唯一的。

備註

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

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

typedef struct EventTracePropertyData {
    EVENT_TRACE_PROPERTIES Props;
    WCHAR LoggerName[128];
    WCHAR LogFileName[1024];
} EventTracePropertyData;

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

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

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

規格需求

最低支援的用戶端	Windows 2000 專業版 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器	Windows 2000 Server [傳統型應用程式 |UWP 應用程式]
標頭	evntrace.h

另請參閱

StartTrace

ControlTrace

QueryAllTraces

記錄模式常數

EVENT_TRACE_PROPERTIES_V2

WNODE_HEADER