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

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

较小的缓冲区大小可减少会话内存使用量，并有助于减少日志文件大小。 较大的缓冲区大小支持收集较大的事件，因为 ETW 不会跨缓冲区边界对事件进行分段，因此无法收集大于缓冲区大小的事件。 在涉及极高数据吞吐量的方案中，较大的缓冲区大小还可以减少 CPU 开销。

• 具有小事件和低事件速率 (几 KB/秒的会话) 应使用 4KB 到 16KB) (较小的缓冲区。
• 具有小事件和中等事件速率的会话应使用中等缓冲区大小 (16KB 到 32KB) 。
• 具有大型事件或高事件速率 (几 MB/s) 的会话应使用 (64KB 到 128KB) 的大型缓冲区。
• 在极少数情况下，当应为每秒具有数百兆字节数据的诊断跟踪保留大量内存时， (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 参数。 这通常是根据预期的事件速率和希望跟踪覆盖的时间量计算的。 例如，如果预期数据速率为每秒 16KB，并且希望跟踪记录至少 60 秒的数据，则需要 960KB。 假设缓冲区大小为 32KB，请将 MinimumBuffers 设置为 30 (960KB/每个缓冲区 32KB = 30 个缓冲区) 。 启动跟踪时，ETW 将保留 (调整) 最小缓冲区数。 填充所有缓冲区后，ETW 将对新事件重复使用最早的填充缓冲区。 请注意，ETW 不会分配其他缓冲区， (ETW 忽略缓冲模式跟踪) 的 MaximumBuffers 。

MaximumBuffers

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

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

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

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

如果事件是由以高 IRQL 运行的驱动程序生成的，则 ETW 无法分配按需缓冲区。 如果跟踪会话需要记录来自高 IRQL 内核模式提供程序的事件，它可能需要使用更高的 MinimumBuffers 值来强制预分配缓冲区。

注意

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

MaximumFileSize

用于记录事件的文件的最大大小（以 MB 为单位）或零（无大小限制）。 通常，在将 LogFileModeEVENT_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 之前： 如果没有实时使用者，则会丢弃事件并继续日志记录。

除非实时使用者使用事件，否则不要启动实时日志记录会话。 没有使用者的实时会话会浪费系统资源 (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)

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

注解

分配此结构的内存时，必须分配足够的内存，以便在结构之后包括会话名称和日志文件名。 会话名称在内存中必须位于日志文件名的前面。 必须将日志文件名复制到偏移量，但不要将会话名称复制到偏移量。 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