EVENT_TRACE_PROPERTIES结构 (evntrace.h)

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

注意

这是版本 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/秒) 应使用 (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 将忽略缓冲模式会话的 MaximumBuffers (会话（包括日志记录模式 EVENT_TRACE_BUFFERING_MODE) ）。 缓冲模式会话始终在跟踪集合开始时分配 MinimumBuffers ，并且永远不会分配其他缓冲区。

MaximumFileSize

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

如果使用系统驱动器 (包含操作系统) 的驱动器进行日志记录，则 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 或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)

  启用要转换为 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_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-terminate 字符串的开头，偏移量) (（以字节为单位）。

文件名通常具有 .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-terminate 字符串的开头) 偏移量 (（以字节为单位）。

重要

对会话使用描述性名称，以便可以从会话名称确定会话的所有权和使用情况。 请勿使用 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