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 |