TraceLoggingWrite 宏 (traceloggingprovider.h)

  • 项目

发出 TraceLogging 事件。

语法

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  __VA_ARGS__
);

参数

[in] hProvider

用于写入事件的 TraceLogging 提供程序 的句柄。

[in] eventName

用于标识事件的短唯一名称。 这必须是字符串文本，而不是变量。 它不能包含任何嵌入 '\0' 字符。

[in, optional] __VA_ARGS__

最多 99 个用于配置或向事件添加字段的其他参数。 每个参数必须是 TraceLogging 包装宏之一，例如 TraceLoggingLevel、 TraceLoggingKeyword 或 TraceLoggingValue。

重要

ProviderId、Level 和 Keyword 是筛选事件的主要方法。 其他类型的筛选是可能的，但开销要高得多。 始终为每个事件分配非零级别和关键字 (keyword) 。

返回值

无

备注

TraceLoggingWrite 宏的每次调用都会扩展为通过指定的提供程序句柄将事件写入 ETW 所需的代码。

  • TraceLoggingWrite 检查指定的提供程序是否已注册。 如果未 注册提供程序， TraceLoggingWrite 不执行任何操作。
  • TraceLoggingWrite 检查是否有任何使用者正在侦听事件，就像通过调用 TraceLoggingProviderEnabled 一样。 如果没有使用者正在侦听事件， TraceLoggingWrite 不执行任何工作。
  • 否则， TraceLoggingWrite 将计算参数中指定的运行时表达式，保存结果，将必要的数据打包到事件中，并调用 EventWriteTransfer 将事件发送到 ETW。

生成的事件将按如下方式构造：

  • 事件的提供程序 ID、提供程序名称和提供程序组将来自 hProvider 参数。
  • 事件的名称将来自 eventName 参数。
  • 在用户模式下，事件的活动 ID 将来自线程的隐式活动 ID。 在内核模式下，将GUID_NULL事件的活动 ID。
  • 该事件将不具有相关的活动 ID。
  • 事件的级别将来自 TraceLoggingLevel 参数。 如果没有 TraceLoggingLevel 参数，则事件的级别将为 5 (WINEVENT_LEVEL_VERBOSE) 。 如果存在多个 TraceLoggingLevel 参数，将使用最后一个参数。 若要启用有效的事件筛选，请始终为每个事件分配有意义的非零级别。
  • 事件的关键字 (keyword) 将来自 TraceLoggingKeyword 参数。 如果没有 TraceLoggingKeyword 参数，则事件关键字 (keyword) 将为 0 (NONE) 。 如果存在多个 TraceLoggingKeyword 参数，则值将一起为 OR。 若要启用有效的事件筛选，请始终为每个事件分配有意义的非零关键字 (keyword) 。
  • 其他事件属性可由 TraceLoggingOpcode、 TraceLoggingDescription、 TraceLoggingEventTag 或 TraceLoggingChannel 等参数设置。
  • 可以使用 TraceLoggingStruct 对事件字段进行分组。
  • 事件字段由字段参数添加，如 TraceLoggingValue、TraceLoggingInt32、TraceLoggingHResult、TraceLoggingString 等。有关详细信息 ，请参阅 TraceLogging 包装器宏 。

例如：

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

的调用 TraceLoggingWrite(hProvider, "EventName", args...) 可视为扩展为代码，如下所示：

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, NULL, NULL, N, data);
}

注意

每个 TraceLoggingWrite 宏都会自动检查 TraceLoggingProviderEnabled ，以便仅当使用者正在侦听来自提供程序的事件时才会写入事件。 因此，通常不需要直接调用 TraceLoggingProviderEnabled。 当 且仅当启用了 事件时，才会计算 中的任何 args... 运行时表达式。 运行时表达式的计算不会超过一次。

如果生成复杂事件，可能会收到编译器错误，指示行太长或编译器已满堆空间。 当 TraceLoggingWrite 宏扩展到一行长于编译器支持的行时，就会发生这种情况。 如果发生这种情况，则需要简化事件。

TraceLoggingWrite 宏使用EVENT_DATA_DESCRIPTOR数组将数据传输到 ETW。 ETW 接受的描述符的最大数目为 128。 由于每个参数可能需要使用 0、1 或 2 个描述符，因此，在达到参数限制 (99) 之前，可能会达到数据描述符限制 (128) 。

重要

尽量避免大型事件。 ETW 主要用于处理小型事件。 TraceLoggingWrite 将以无提示方式删除任何太大的事件。 事件的大小基于 ETW 运行时) (添加的事件标头总数，元数据 (即提供程序名称、事件名称、字段名称、字段类型) 以及数据 (字段值) 。 如果事件的总大小大于 65535，或者使用者会话使用的缓冲区大小小于事件的大小，则不会记录该事件。

对 TraceLoggingWrite 的调用与对 TraceLoggingWriteActivity 的调用相同，pActivityId 和 pRelatedActivityId 参数为 NULL。 如果需要为事件指定活动 ID，请使用 TraceLoggingWriteActivity 。

示例

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider,  // Name of the provider handle
    "MyProvider", // Human-readable name of the provider
    // ETW Control GUID: {b3864c38-4273-58c5-545b-8b3608343471}
    (0xb3864c38,0x4273,0x58c5,0x54,0x5b,0x8b,0x36,0x08,0x34,0x34,0x71));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

要求

   
最低受支持的客户端 Windows Vista [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2008 [桌面应用 | UWP 应用]
目标平台 Windows
标头 traceloggingprovider.h
Library Advapi32.lib

另请参阅

EventWriteTransfer

TraceLoggingWriteActivity

TraceLogging 包装宏