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生成的代码所调用的库代码。

为您的事件提供者创建一个新的GUID

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

有许多可以创建GUID的工具，例如

• 在Visual Studio中，在“工具”菜单中选择“创建GUID”。
• 从Visual Studio命令行运行 uuidgen.exe。
• 在Ubuntu shell中运行 uuidgen。

许多用于处理事件的工具期望提供者的GUID基于提供者的名称，并且此技术由Microsoft推荐。生成与这些工具兼容的GUID的方法包括

• PowerShell: [System.Diagnostics.Tracing.EventSource]::new("YourProviderName").Guid
• Visual Studio 2022：从“调试”菜单中选择“性能分析器”。点击“事件查看器”旁边的齿轮图标。在“附加提供者”下，输入您的“提供者名称”，“提供者GUID”将自动填写。
• 在TraceView中，从“文件”菜单中选择“创建新日志会话”。选择“手动输入控制GUID或哈希名称”并输入 * 后跟您的提供者名称（例如，*YourProviderName）。然后，点击“确定”。在“格式信息源选择”窗口中，选择“自动”并点击“确定”。GUID将显示。
• 有关其他工具和代码，请参阅这篇StackOverflow帖子

定义事件提供者和其事件

将特性定义添加到您的源代码中，并使用您刚才创建的GUID使用宏 #[trace_logging_provider(guid = "...")] 进行注释。特性定义仅用作过程宏的输入；特性不会输出到您的crate中，也不能用作正常特性。

ETW提供者名称在ETW元数据中基于特性名称。这可以通过在提供者属性中显式指定名称来覆盖，例如 #[trace_logging_provider(name = "YourNameHere")]。

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

宏 #[trace_logging_provider]] 消耗特质定义并生成相同名称和相同方法签名的 struct 定义。 （特质 不 可用于普通特质。）

# use win_etw_macros::trace_logging_provider;
#[trace_logging_provider(guid = "... your guid here ...")]
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);
    // ...
}

let my_app_events = MyAppEvents::new();

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