traceloggingprovider.h 标头
TraceLogging 是一种系统,用于记录可在不带清单的情况下解码的自描述事件。 在 Windows 上,TraceLogging 用于 为 Windows (ETW) 事件生成事件跟踪。
Windows SDK 中的 TraceLoggingProvider.h 标头包含宏和内联函数,用于使用 C 或 C++ 为内核和用户模式代码生成 TraceLogging 编码的 ETW 事件。
注意
TraceLoggingProvider.h 需要事件属性(如提供程序名称、事件名称和字段名称)的编译时常量值。 为了最大程度地减少运行时开销, TraceLoggingProvider.h 在编译时生成其数据结构,并将信息存储在只读内存中。 如果需要生成运行时动态事件,则需要使用不同的 TraceLogging 实现,例如 TraceLoggingDynamic。
快速启动
- 在 .c 或 .cpp 文件中,使用 TRACELOGGING_DEFINE_PROVIDER 宏声明全局提供程序句柄。 提供程序句柄表示组件与 ETW 的连接。
- 在组件启动 (例如 、
wmain
、DllMain
或DriverEntry
) 中main
,使用 TraceLoggingRegister 函数打开组件与 ETW 的连接。 - 在组件关闭时,使用 TraceLoggingUnregister 函数关闭组件与 ETW 的连接。
- 在组件执行期间,使用 TraceLoggingWrite 宏生成 TraceLogging 编码的 ETW 事件。
- 根据需要,在标头中使用 TRACELOGGING_DECLARE_PROVIDER 宏来转发提供程序句柄,以便它可以在组件的其他部分使用。
- 使用 WPR、 tracelog 或 traceview 等工具来收集跟踪。
- 使用 WPA、 tracefmt 或 traceview 等工具来解码和查看跟踪。
示例
#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
"MyCompany.MyComponent", // Human-readable name for the provider
// {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
(0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));
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;
}
有关详细信息,请参阅:
- TraceLogging
- TraceLogging 包装宏
- TraceLoggingWrite
- TRACELOGGING_DECLARE_PROVIDER
- TRACELOGGING_DEFINE_PROVIDER
traceloggingprovider.h 包含以下编程接口:
函数
TRACELOGGING_DECLARE_PROVIDER 向前声明 TraceLogging 提供程序的句柄。 |
TRACELOGGING_DEFINE_PROVIDER 定义 TraceLogging 提供程序的句柄。 |
TRACELOGGING_DEFINE_PROVIDER_STORAGE 为将由用户定义的 TraceLogging 提供程序句柄保留静态存储。 首选TRACELOGGING_DEFINE_PROVIDER而不是此宏。 |
TraceLoggingBinary TraceLogging 包装器宏,用于向事件添加具有二进制数据的字段。 |
TraceLoggingChannel 用于设置事件的通道的 TraceLogging 包装器宏。 |
TraceLoggingCustom TraceLogging 包装器宏,用于将使用自定义序列化程序打包的字段添加到事件。 |
TraceLoggingCustomAttribute TraceLogging 包装器宏,用于将有关事件的自定义信息添加到 PDB 中。 |
TraceLoggingDescription 用于设置事件说明的 TraceLogging 包装器宏。 |
TraceLoggingEventTag TraceLogging 包装宏,用于设置事件的事件标记。 |
TraceLoggingKeyword 用于设置事件关键字 (keyword) 的 TraceLogging 包装器宏。 |
TraceLoggingLevel 用于设置事件的级别的 TraceLogging 包装宏 |
TraceLoggingOpcode 用于设置事件的操作码的 TraceLogging 包装宏 |
TraceLoggingOptionGroup traceLogging 宏,用于TRACELOGGING_DEFINE_PROVIDER指定提供程序组。 |
TraceLoggingProviderEnabled TraceLogging 宏,用于确定是否有任何跟踪使用者正在侦听来自此提供程序的事件。 |
TraceLoggingProviderId 获取 TraceLogging 提供程序的提供程序 ID。 |
TraceLoggingRegister 注册 TraceLogging 提供程序,以便可用于记录事件。 |
TraceLoggingRegisterEx 注册 TraceLogging 提供程序,以便可用于记录事件,并指定 ETW 启用回调。 |
TraceLoggingSetInformation 通过调用 EventSetInformation 配置 TraceLogging 提供程序。 |
TraceLoggingSocketAddress TraceLogging 包装宏,用于向事件添加具有套接字地址的字段。 |
TraceLoggingStruct TraceLogging 包装器宏,用于向事件添加包含其他字段的字段。 |
TraceLoggingUnregister 注销 TraceLogging 提供程序。 |
TraceLoggingValue 用于 C++ 的 TraceLogging 包装宏,用于向事件添加具有自动推导类型的字段。 |
TraceLoggingWrite 发出 TraceLogging 事件。 |
TraceLoggingWriteActivity 发出具有指定活动 ID 的 TraceLogging 事件。 |