Event Tracing Windows (ETW) Flutter 插件 #

一个用于 Windows 平台的 Flutter 插件，利用 ETW (Event Tracing for Windows) 实现进程和文件系统的实时监控功能。

功能特性 #

✅ 进程监控：实时监听系统中所有进程的启动和终止事件
✅ 文件系统监控：监听文件的创建、删除、修改和重命名事件
✅ 实时事件流：通过 Stream 接口实时接收事件通知
✅ 高性能：基于 Windows ETW 底层 API，性能优异
✅ 详细信息：提供进程 ID、进程名称、文件路径、时间戳等详细信息

系统要求 #

Windows 7 或更高版本
管理员权限：ETW 监控需要管理员权限才能运行
Flutter 3.3.0 或更高版本

安装 #

在 pubspec.yaml 中添加依赖：

dependencies:
  event_tracing_windows: ^0.0.1

然后运行：

flutter pub get

使用方法 #

基本用法 #

import 'package:event_tracing_windows/event_tracing_windows.dart';

final plugin = EventTracingWindows();

// 开始监听进程事件
await plugin.startProcessMonitoring();

// 订阅进程事件流
plugin.processEventStream.listen((event) {
  print('进程事件: ${event.processName} (PID: ${event.processId})');
  if (event.type == ProcessEventType.started) {
    print('进程启动');
  } else {
    print('进程终止');
  }
});

// 停止监听
await plugin.stopProcessMonitoring();

进程监控 #

// 启动进程监控
bool success = await plugin.startProcessMonitoring();
if (success) {
  // 监听进程事件
  plugin.processEventStream.listen((ProcessEvent event) {
    print('类型: ${event.type}');
    print('进程 ID: ${event.processId}');
    print('进程名称: ${event.processName}');
    print('可执行文件路径: ${event.executablePath}');
    print('父进程 ID: ${event.parentProcessId}');
    print('命令行: ${event.commandLine}');
    print('时间戳: ${event.timestamp}');
  });
}

// 停止进程监控
await plugin.stopProcessMonitoring();

文件系统监控 #

// 启动文件系统监控
bool success = await plugin.startFileMonitoring();
if (success) {
  // 监听文件事件
  plugin.fileEventStream.listen((FileEvent event) {
    print('类型: ${event.type}');
    print('文件路径: ${event.filePath}');
    print('新文件路径: ${event.newFilePath}'); // 仅重命名事件
    print('进程 ID: ${event.processId}');
    print('进程名称: ${event.processName}');
    print('时间戳: ${event.timestamp}');
  });
}

// 停止文件系统监控
await plugin.stopFileMonitoring();

API 文档 #

EventTracingWindows 类 #

方法

Future<bool> startProcessMonitoring(): 开始监听进程事件
Future<bool> stopProcessMonitoring(): 停止监听进程事件
Future<bool> startFileMonitoring(): 开始监听文件系统事件
Future<bool> stopFileMonitoring(): 停止监听文件系统事件
Stream<ProcessEvent> get processEventStream: 获取进程事件流
Stream<FileEvent> get fileEventStream: 获取文件事件流

ProcessEvent 类 #

进程事件数据模型：

class ProcessEvent {
  final ProcessEventType type;        // 事件类型（started/terminated）
  final int processId;                 // 进程 ID
  final String processName;            // 进程名称
  final String? executablePath;        // 可执行文件路径
  final int? parentProcessId;          // 父进程 ID
  final String? commandLine;           // 命令行参数
  final int timestamp;                 // 时间戳（Windows FILETIME 格式）
}

ProcessEventType 枚举

enum ProcessEventType {
  started,     // 进程启动
  terminated,  // 进程终止
}

FileEvent 类 #

文件事件数据模型：

class FileEvent {
  final FileEventType type;      // 事件类型
  final String filePath;         // 文件路径
  final String? newFilePath;     // 新文件路径（仅重命名事件）
  final int processId;           // 触发事件的进程 ID
  final String? processName;     // 触发事件的进程名称
  final int timestamp;           // 时间戳（Windows FILETIME 格式）
}

FileEventType 枚举

enum FileEventType {
  created,   // 文件创建
  deleted,   // 文件删除
  modified,  // 文件修改
  renamed,   // 文件重命名
}

运行示例 #

本插件包含一个完整的示例应用，展示了如何使用所有功能。

以管理员权限运行 #

重要：ETW 监控需要管理员权限，必须以管理员身份运行应用。

方法 1：通过命令行

# 进入示例目录
cd example

# 以管理员权限打开 PowerShell，然后运行
flutter run -d windows

方法 2：通过 Visual Studio

构建应用：
```
cd example
flutter build windows
```
找到生成的 exe 文件（通常在 example\build\windows\x64\runner\Release\）
右键点击 exe 文件，选择"以管理员身份运行"

示例应用功能 #

示例应用包含两个标签页：

进程监控：
- 实时显示所有进程的启动和终止事件
- 显示进程 ID、名称、路径等详细信息
- 可以开始/停止监控，清除事件记录
文件监控：
- 实时显示文件的创建、删除、修改和重命名事件
- 显示文件路径、触发进程等信息
- 可以开始/停止监控，清除事件记录

技术实现 #

Windows 端 (C++) #

插件使用 Windows ETW (Event Tracing for Windows) API：

StartTrace(): 启动 ETW 会话
EnableTraceEx2(): 启用内核提供程序（进程、文件）
OpenTrace() / ProcessTrace(): 处理 ETW 事件
TdhGetEventInformation(): 解析事件数据

主要组件：

EtwSession: ETW 会话基类
ProcessMonitorSession: 进程监控会话
FileMonitorSession: 文件监控会话

Dart 端 #

使用 Flutter 平台通道进行通信：

MethodChannel: 用于控制命令（开始/停止监控）
EventChannel: 用于实时事件流传输

权限说明 #

此插件需要管理员权限，原因如下：

ETW 内核提供程序：访问内核级事件需要管理员权限
系统范围监控：监控所有进程和文件系统活动需要提升的权限
安全限制：Windows 系统出于安全考虑限制普通用户访问这些 API

如果没有管理员权限，启动监控将会失败并返回 false。

性能考虑 #

ETW 是 Windows 内置的高性能事件追踪系统
事件处理在独立线程中进行，不会阻塞主线程
示例应用限制显示最近 100 个事件以保持性能
在生产环境中，建议添加事件过滤逻辑以减少不必要的处理

限制和已知问题 #

仅支持 Windows：此插件仅适用于 Windows 平台
需要管理员权限：无法在普通用户权限下运行
事件数量：系统中的事件非常频繁，建议添加过滤
某些事件信息可能不完整：取决于 ETW 提供程序返回的数据

故障排除 #

启动监控失败 #

问题：调用 startProcessMonitoring() 或 startFileMonitoring() 返回 false

解决方案：

确保以管理员权限运行应用
检查 Windows 事件查看器中是否有相关错误
确保没有其他 ETW 会话占用相同的会话名称

没有收到事件 #

问题：监控已启动但没有收到事件

解决方案：

确认已正确订阅事件流（processEventStream 或 fileEventStream）
检查是否有实际的进程或文件活动发生
查看调试输出中是否有错误信息

贡献 #

欢迎提交 Issues 和 Pull Requests！

许可证 #

本项目基于 MIT 许可证开源。详见 LICENSE 文件。

更新日志 #

0.0.1 #

初始版本
支持进程监控
支持文件系统监控
提供实时事件流
包含示例应用

event_tracing_windows 0.0.1 event_tracing_windows: ^0.0.1 copied to clipboard

Metadata