TraceLoggingWriteActivity 宏 (traceloggingprovider.h)

  • 项目

发出具有指定活动 ID 的 TraceLogging 事件。

语法

void TraceLoggingWriteActivity(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  pActivityId,
  [in, optional]  pRelatedActivityId,
  [in, optional]  __VA_ARGS__
);

参数

[in] hProvider

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

[in] eventName

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

[in, optional] pActivityId

事件的活动 ID，或使用默认值的 NULL。

[in, optional] pRelatedActivityId

事件的相关活动 ID;对于没有相关活动 ID，则为 NULL。

[in, optional] __VA_ARGS__

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

重要

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

返回值

无

备注

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

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

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

  • 事件的提供程序 ID、提供程序名称和提供程序组将来自 hProvider 参数。
  • 事件的名称将来自 eventName 参数。
  • 事件的活动 ID 将来自 pActivityId 参数。 如果 pActivityId 为 NULL，则用户模式事件将使用线程的隐式活动 ID，内核模式事件将使用GUID_NULL。
  • 事件的相关活动 ID 将来自 pRelatedActivityId 参数。 如果 pRelatedActivityId 为 NULL，则事件将没有相关的活动 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 Wrapper 宏 。

例如：

TraceLoggingWriteActivity(
    g_hProvider,
    "MyEvent1",
    &myActivityGuid,
    NULL, // no related activity ID
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

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

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

注意

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

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

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

重要

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

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

有关 ActivityId 和 RelatedActivityId 参数的语义的信息，请参阅 EventWriteTransfer。

有关在 ETW 中编写活动的信息 ，请参阅 EventActivityIdControl 。

请参阅用于帮助管理 TraceLogging ETW 活动的 C++ 类的 TraceLoggingActivity。

要求

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

另请参阅

EventActivityIdControl

EventWriteTransfer

TraceLoggingActivity

TraceLoggingWrite

TraceLogging 包装宏