Rust 对 Windows 事件跟踪 (ETW) 的支持

提供了 #[trace_logging_provider] 宏，该宏允许您为与 跟踪日志提供程序 一起使用的 Windows 事件跟踪 (ETW) 框架定义一个 跟踪日志提供程序。

此宏仅用于针对 Windows 的情况。当针对其他平台时，此宏仍然可以工作，但将生成不执行任何操作的代码。

此框架允许应用程序记录结构化事件，而不是文本字符串。ETW 分析工具可以可靠地识别您事件中的字段，并将它们作为强类型数据而不是文本字符串来处理。

有关使用 ETW 的 tracing，请参阅 tracing-etw。

如何创建和使用事件提供程序

在 ETW 中，一个 事件提供程序 是一个生成事件的软件对象。 事件控制器 设置事件日志会话，而 事件消费者 读取并解释事件数据。这个 crate 专注于使应用程序能够创建 事件提供程序。

添加 crate 依赖项

将这些依赖项添加到您的 Cargo.toml 文件中

[dependencies]
win_etw_macros = "0.1.*"
win_etw_provider = "0.1.*"

win_etw_macros 包含生成事件代码的过程宏。 win_etw_provider 包含由 win_etw_macros 生成的代码调用的库代码。

定义事件提供程序及其事件

将特性定义添加到您的源代码中，并用#[trace_logging_provider]宏进行注释。该宏消耗特性定义，并生成具有相同名称和相同方法签名的struct定义。（特性不能作为普通特性使用。）

#[trace_logging_provider]
pub trait MyAppEvents {}

每个事件提供程序必须具有唯一的名称和GUID。 ETW使用此GUID来识别由您的提供程序生成的事件。Windows包含许多事件提供程序，因此能够仅选择由您的应用程序生成的事件非常重要。此GUID也由ETW内部用于识别事件元数据（字段类型），因此您的GUID必须是唯一的。否则，使用相同GUID的冲突源的事件可能会被错误解释。

指定您的提供程序名称

除非重写，否则#[trace_logging_provider]使用您的特性定义的名称作为ETW提供程序的名称（如上例中的"MyAppEvents"）。要指定不同的名称，请使用#[trace_logging_provider(name = "MyCompany.MyComponent")]指定名称。

为您的事件提供程序生成GUID

如果您未指定guid参数，#[trace_logging_provider]宏将生成一个基于名称的.NET EventSource兼容GUID。生成的GUID与以下PowerShell代码生成的GUID相同：[System.Diagnostics.Tracing.EventSource]::new("MyCompany.MyComponent").Guid。GUID可以通过名为PROVIDER_GUID的关联常量从您的Rust代码中访问（例如，MyAppEvents::PROVIDER_GUID）。

如果您不希望使用基于名称的GUID，您可以使用类似uuidgen的工具（可在Visual Studio命令行或Ubuntu shell中获取）生成GUID，并用#[trace_logging_provider(guid = "... your guid here ...")]指定。

向您的提供程序添加事件

在特性定义中添加方法签名。每个方法签名定义一个事件类型。每个方法参数定义事件类型的字段。仅支持有限数量的字段类型（以下列举）。

use win_etw_macros::trace_logging_provider;
#[trace_logging_provider(name = "MyCompany.MyComponent")]
pub trait MyAppEvents {
    fn http_request(client_address: &SockAddr, is_https: bool, status_code: u32, status: &str);
    fn database_connection_created(connection_id: u64, server: &str);
    fn database_connection_closed(connection_id: u64);
    // ...
}

创建事件提供程序实例

在初始化时（在你的 fn main() 等），创建事件提供者实例

let my_app_events = MyAppEvents::new();

你的应用程序应为每个事件提供者创建单个实例，每个进程一个。也就是说，你应该创建一个事件提供者实例并在进程间共享它。通常，实例存储在静态变量中，使用懒加载/原子赋值。有许多crate和类型可以支持这种使用模式。

调用事件方法来报告事件

要报告事件，请调用事件提供者上定义的一个方法。该方法将调用ETW来报告事件，但不能保证事件被存储或转发；如果事件缓冲区资源稀缺，事件可能会丢失。

my_app_events.client_connected(None, &"192.168.0.42:6667".parse(), false, 100, "OK");

注意，所有生成的事件方法都有一个附加的第一个参数，options: Option<&EventOptions>。此参数允许你覆盖每个事件的自定义参数，例如事件级别和事件相关ID。在大多数情况下，你应该传递 None。

支持的字段类型

仅支持有限的字段类型。

• 64位及以下的整数原语：i8、i16、i32、i64、u8、u16、u32、u64
• 浮点数原语：f32、f64
• 架构相关的尺寸：usize、isize。
• 布尔值：bool
• 所有支持原语切片：&[u8]、&[u16] 等。
• 支持 Windows FILETIME。类型必须严格声明为 FILETIME；类型别名或完全限定路径（如 winapi::shared::minwindef::FILETIME）将不起作用。生成的代码中的参数类型将是 win_etw_provider::FILETIME，这是基于 u64 的新类型。
• std::time::SystemTime 受支持，但它必须严格声明为 SystemTime；类型别名或完全限定路径（如 std::time::SystemTime）将不起作用。
• SockAddr、SockAddrV4 和 SockAddrV6 均受支持。它们必须按照所示声明，不得使用完全限定名称或类型别名。

如何捕获和查看事件

有多种工具可用于捕获和查看 ETW 事件。最简单的工具是来自 Windows SDK 的 TraceView 工具。通常安装在以下路径：C:\Program Files (x86)\Windows Kits\10\bin\10.0.<xxxxx>.0\x64\traceview.exe，其中 <xxxxx> 是 Windows SDK 的版本号。

运行 TraceView，然后选择“文件”，然后“创建新日志会话”。选择“手动输入 GUID 或哈希名称”并输入您为事件提供程序分配的 GUID。点击确定。下一个对话框将提示您选择 WPP 格式信息的来源；选择自动并点击确定。

此时，TraceView 应该正在捕获事件（对于您的分配的 GUID）并在实时显示它们，无论哪个进程报告了这些事件。

这些工具也可以用于捕获 ETW 事件

• Windows 性能记录器 此工具旨在捕获系统级事件流。对于捕获特定事件提供程序的事件，它并不有用。
• logman 是一个用于管理事件的命令行工具。
• Tracelog

还有其他工具，如 Windows 性能记录器，可以捕获 ETW 事件。

改进建议

• 更好的处理每个事件的覆盖，而不是使用 Option<&EventOptions>。

参考资料

• Windows 事件跟踪 (ETW) 简化
• Windows 事件跟踪 (ETW) 的 TraceLogging
• 记录和查看 TraceLogging 事件
• TraceLoggingOptionGroup
• 提供者特性
• TRACELOGGING_DEFINE_PROVIDER 宏

贡献

此项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议 (CLA)，声明您有权并且实际上确实授予我们使用您的贡献的权利。有关详细信息，请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人将自动确定您是否需要提供 CLA 并相应地装饰 PR（例如，状态检查、注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们的 CLA 的所有存储库中做一次。

此项目已采用 Microsoft 开源行为准则。有关更多信息，请参阅 行为准则常见问题解答 或联系 opencode@microsoft.com 询问任何其他问题或意见。