EVENT_TRACE_PROPERTIES_V2 结构 (evntrace.h)

EVENT_TRACE_PROPERTIES_V2 结构包含有关事件跟踪会话的信息。 定义、更新或查询会话的属性时，可以将此结构与 StartTrace 和 ControlTrace 等 API 配合使用。

注意

这是版本 2 结构，从 EVENT_TRACE_PROPERTIES 结构扩展。 从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

为每个事件跟踪会话缓冲区分配的千字节内存。 最小缓冲区大小为 4 (4KB) 。 最大缓冲区大小为 16384 (16MB) 。 大多数跟踪会话应使用 64KB 或更小的缓冲区大小，以避免浪费内存和磁盘空间。 Windows 8之前：最大缓冲区大小为 1024 (1MB) 。

较小的缓冲区大小可减少会话内存使用量。 更大的缓冲区大小 (高达 64KB) 支持收集较大的事件 -- ETW 无法收集大于缓冲区大小的事件，并且无论缓冲区大小如何，都无法收集大于 64KB 的事件。 在涉及极高数据吞吐量的情况下，较大的缓冲区大小可以减少 CPU 开销。

• 具有小事件和低事件速率的会话 (几 KB/秒) 应使用 (4KB 到 16KB) 较小的缓冲区大小。
• 具有小型事件和中等事件速率的会话应使用中等缓冲区大小 (16KB 到 32KB) 。
• 具有大型事件或高事件速率 (几 MB/s) 的会话应使用 (64KB 到 128KB) 的大型缓冲区大小。
• 在极少数情况下，当应为每秒数百兆字节数据的诊断跟踪保留大量内存时， (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 可能会将其降低到限制，以避免过多的内存使用量。

对于具有中等事件速率的文件模式和实时跟踪，大多数用户应通过将 MinimumBuffers 设置为 0 或较小的最小 (（例如 4 或 8) ）来最大程度地减少内存使用量，从而允许 ETW 根据处理器数向上调整值。 启动跟踪时，ETW 将保留 (调整) 最小缓冲区数。 如果缓冲区的填充速度超过处理速度，则 ETW 将分配加法缓冲区，上限为 MaximumBuffers 指定的数量。

对于缓冲模式 (循环内存中) 跟踪，用户应根据希望 ETW 为会话保留的总内存量设置 MinimumBuffers 参数。 这通常基于预期的事件速率和希望跟踪涵盖的时间量来计算。 例如，如果预期数据速率为每秒 16KB，并且希望跟踪记录至少 60 秒的数据，则需要 960KB。 假设缓冲区大小为 32KB，请将 MinimumBuffers 设置为 30 (960KB/32KB/每个缓冲区 = 30 个缓冲区) 。 启动跟踪时，ETW 将保留 (调整) 最小缓冲区数。 当所有缓冲区都已填充时，ETW 将对新事件重复使用最早的填充缓冲区。 请注意，ETW 不会分配其他缓冲区， (ETW 忽略缓冲模式跟踪的 MaximumBuffers) 。

MaximumBuffers

要为跟踪会话的缓冲池分配的最大缓冲区数。

在某些情况下，ETW 可能会调整此值。

• 如果此值小于 MinimumBuffers 的调整值，ETW 可能会将其增加到等于或大于 MinimumBuffers 的合适值。
• 如果此值大于 ETW 确定的限制，ETW 可能会将其降低到限制。

大多数用户应通过将 MinimumBuffers 和 MaximumBuffers 设置为相同的值来开始优化其会话。 然后，如果跟踪在事件速率峰值期间删除事件，则可以增加 MaximumBuffers 的值。

注意

ETW 忽略缓冲模式会话 (包含日志记录模式 EVENT_TRACE_BUFFERING_MODE) 的会话的此字段。 缓冲模式会话始终在跟踪集合开始时分配 MinimumBuffers ，并且从不分配其他缓冲区。

MaximumFileSize

用于记录事件的文件的最大大小（以 MB 为单位）或零（无大小限制）。 通常，在将 LogFileMode 设置为 EVENT_TRACE_FILE_MODE_CIRCULAR时，使用此成员来限制循环日志文件的大小。 如果 LogFileMode 包含 EVENT_TRACE_FILE_MODE_PREALLOCATE或 EVENT_TRACE_FILE_MODE_NEWFILE，EVENT_TRACE_FILE_MODE_CIRCULAR则必须将此成员设置为非零值。

如果使用系统驱动器 (包含用于日志记录的操作系统) 的驱动器，则 ETW 会检查额外的 200MB 磁盘空间，而不考虑是否使用最大文件大小参数。 因此，如果将 100MB 指定为系统驱动器中跟踪文件的最大文件大小，则驱动器上需要有 300MB 的可用空间。

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 或会话 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)

  允许将 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_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： 会话名称区分大小写。 因此，允许名称仅大小写不同的会话。 但是，为了减少混淆，应确保会话名称是唯一的。

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 版本 1703 之前Windows 10版本的系统兼容，并将被视为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