EVENT_TRACE_LOGFILEW 结构 (evntrace.h)

  • 项目

EVENT_TRACE_LOGFILE结构存储有关跟踪数据源的信息。

调用 OpenTrace 时使用 EVENT_TRACE_LOGFILE 结构。 用户提供 EVENT_TRACE_LOGFILE 结构，其中包含有关跟踪数据源的信息， (ETL 文件的名称或活动实时记录器会话的名称) 、跟踪处理标志以及将接收跟踪数据的回调函数。 成功后， OpenTrace 将填充结构的剩余字段，以返回有关跟踪数据源的详细信息。

ProcessTrace 处理缓冲区时，它会使用EVENT_TRACE_LOGFILE结构调用用户定义的 BufferCallback，以提供有关事件处理会话和缓冲区的信息。

语法

typedef struct _EVENT_TRACE_LOGFILEW {
  LPWSTR                        LogFileName;
  LPWSTR                        LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKW BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEW, *PEVENT_TRACE_LOGFILEW;

成员

LogFileName

正在处理的日志文件的名称;如果处理来自实时跟踪会话的数据，则为 NULL 。 如果要调用 OpenTrace 以使用日志文件中的数据，请为此成员指定一个值。

调用 OpenTrace 时，如果 LoggerName 为非 NULL ，则 LogFileName 必须为 NULL。

调用 OpenTrace 时，使用事件的用户必须具有读取文件的权限。

注意

通过 LogFileName 字段提供给 OpenTrace 的文件名必须是完整文件名，包括任何后缀。 某些跟踪文件创建 API 可以无提示地将后缀添加到用户指定的文件名。 例如，如果控制器将事件记录到专用会话 (控制器在调用 StartTrace) 时将 EVENT_TRACE_PROPERTIES 的 LogFileMode 成员设置为EVENT_TRACE_PRIVATE_LOGGER_MODE，则生成的 ETL 文件将包含进程 ID 后缀，例如 。 mytrace.etl_123 如果文件是使用 EVENT_TRACE_FILE_MODE_NEWFILE 模式创建的，则也会发生这种情况，在这种情况下，生成的 ETL 文件将包含序列号。

LoggerName

实时事件跟踪会话的名称;如果处理日志文件中的数据，则为 NULL 。 如果要调用 OpenTrace 以使用实时会话中的数据，请为此成员指定一个值。

调用 OpenTrace 时，如果 LogFileName 为非 NULL ，则 LoggerName 必须为 NULL。

仅当跟踪控制器已将 EVENT_TRACE_PROPERTIES 的 LogFileMode 成员设置为包含EVENT_TRACE_REAL_TIME_MODE标志时，才能实时使用事件。

只有具有管理权限的用户、性能日志用户组中的用户以及作为 LocalSystem、LocalService、NetworkService 运行的应用程序才能实时使用事件。 若要授予受限用户实时使用事件的能力，请将这些用户添加到性能日志用户组或调用 EventAccessControl。

Windows XP 和 Windows 2000： 任何人都可以使用实时事件。

CurrentTime

输出时，当前时间，以 1601 年 1 月 1 日午夜以来的 100 纳秒间隔。

BuffersRead

输出时，处理的缓冲区数。

DUMMYUNIONNAME

DUMMYUNIONNAME.LogFileMode

保留。 请勿使用。

DUMMYUNIONNAME.ProcessTraceMode

用于处理事件的模式。 模式在 evntcons.h 头文件中定义。 可以指定以下一种或多种模式：

  • PROCESS_TRACE_MODE_EVENT_RECORD

    如果要以新 EVENT_RECORD 格式接收事件 (强烈建议) ，请指定此模式。 若要以新格式接收事件，必须在 EventRecordCallback 成员中指定回调。 如果未指定此模式，将通过 EventCallback 成员中指定的回调接收旧格式的事件。

    在 Windows Vista 之前： 不支持。

  • PROCESS_TRACE_MODE_RAW_TIMESTAMP

    默认情况下， ProcessTrace 将事件的 TimeStamp 从原始格式 (系统时间、QPC 时间或 CPU 周期计数器) 转换为系统时间， (1601 年 1 月 1 日午夜) 100 纳秒间隔。

    如果不希望将 EVENT_HEADER 的 TimeStamp 成员中的时间戳值EVENT_TRACE_HEADER转换为系统时间，请指定PROCESS_TRACE_MODE_RAW_TIMESTAMP标志。 如果指定了此标志， ProcessTrace 将保留EVENT_TRACE_PROPERTIES 的 Wnode.ClientContext 成员中指定的原始 格式的时间戳值。

    在 Windows Vista 之前： 不支持。

  • PROCESS_TRACE_MODE_REAL_TIME

    指定此模式以实时接收事件。 如果 LoggerName 不为 NULL，则必须指定此模式。

CurrentEvent

输出时， EVENT_TRACE 结构，其中包含处理的最后一个事件。

LogfileHeader

输出时， TRACE_LOGFILE_HEADER 结构，其中包含有关会话和运行会话的计算机的一般信息。

BufferCallback

指向 BufferCallback 函数的指针，该函数接收每个缓冲区 ETW 刷新的缓冲区相关统计信息。 ETW 在传递缓冲区中的所有事件后调用此回调。 此回调是可选的。

BufferSize

输出时，包含每个缓冲区的大小（以字节为单位）。

Filled

输出时，包含缓冲区中包含有效信息的字节数。

EventsLost

未使用。

DUMMYUNIONNAME2

DUMMYUNIONNAME2.EventCallback

指向 ETW 为缓冲区中的每个事件调用 的 EventCallback 函数的指针。 仅当 ProcessTraceMode 字段不包含 标志时， PROCESS_TRACE_MODE_EVENT_RECORD 才使用此字段。

注意

如果 ProcessTraceMode 字段包含 PROCESS_TRACE_MODE_EVENT_RECORD 标志，EventCallback 字段将被视为 EventRecordCallback。 如果 EventCallback 从 ProcessTrace 接收乱码数据，请验证 ProcessTraceMode 字段是否不包含标志 PROCESS_TRACE_MODE_EVENT_RECORD 。

提示

新代码应使用 EventRecordCallback 而不是 EventCallback。 EventRecordCallback 接收包含更完整的事件信息的EVENT_RECORD可与 TdhGetEventInformation 等解码 API 一起使用，并且具有可供回调使用的上下文指针。

DUMMYUNIONNAME2.EventRecordCallback

指向 ETW 为缓冲区中的每个事件调用 的 EventRecordCallback 函数的指针。 仅当 ProcessTraceMode 字段包含 标志时， PROCESS_TRACE_MODE_EVENT_RECORD 才使用此字段。

注意

如果 ProcessTraceMode 字段不包含 标志，PROCESS_TRACE_MODE_EVENT_RECORDEventRecordCallback 字段将被视为 EventCallback。 如果 EventRecordCallback 从 ProcessTrace 接收乱码数据，请验证 ProcessTraceMode 字段是否包含 标志 PROCESS_TRACE_MODE_EVENT_RECORD 。

在 Windows Vista 之前： 不支持。

IsKernelTrace

在输出中，如果此成员为 TRUE，则事件跟踪会话是 NT 内核记录器。 否则，它是另一个事件跟踪会话。

Context

使用者在调用 OpenTrace 时可以指定的上下文数据。 如果使用者使用 EventRecordCallback 来使用事件，则 ETW 将 EVENT_RECORD 结构的 UserContext 成员设置为此值。

在 Windows Vista 之前： 不支持。

注解

事件使用者应：

  1. 将此结构的内存初始化为零。
  2. 如果从 ETL 文件读取数据，请将 LogFileName 设置为文件的路径。 否则， (也就是说，如果从实时会话) 读取，请将 LoggerName 设置为会话的名称，并将 ProcessTraceMode 设置为PROCESS_TRACE_MODE_REAL_TIME。
  3. 如果使用 EventRecordCallback (建议) ，请将 EventRecordCallback 设置为事件记录回调函数的地址，将 Context 设置为要提供给回调的值，然后添加到 PROCESS_TRACE_MODE_EVENT_RECORDProcessTraceMode。 否则 (即，如果使用 EventCallback) ，请将 EventCallback 设置为事件回调函数的地址。
  4. 如果在处理每个缓冲区后需要回调，请将 BufferCallback 设置为缓冲区回调函数的地址。
  5. 如果需要原始时间戳数据而不是已处理的时间戳，请将 添加到 PROCESS_TRACE_MODE_RAW_TIMESTAMPProcessTraceMode。
  6. 调用 OpenTrace。 请注意，如果成功， OpenTrace 函数将使用来自跟踪数据源的信息填充此结构的成员。
  7. 使用 OpenTrace 返回的句柄调用 ProcessTrace。
    • ProcessTrace 将为每个事件调用事件回调函数。
    • ProcessTrace 将在完成每个缓冲区后) (调用缓冲区回调函数，并将包含包含跟踪处理状态信息的 EVENT_TRACE_LOGFILE 结构的实例。
  8. 跟踪处理完成后，调用 CloseTrace 以关闭 OpenTrace 返回的句柄。

注意

evntrace.h 标头将 EVENT_TRACE_LOGFILE 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
标头 evntrace.h

另请参阅

BufferCallback

EventRecordCallback

OpenTrace