尧图网页设计 
eCapture Protobuf Debugger基于 WebSocket 的 Protobuf 事件流实时可视化调试工具【免费下载链接】ecaptureCapturing SSL/TLS plaintext without a CA certificate using eBPF. Supported on Linux/Android kernels for amd64/arm64.项目地址: https://gitcode.com/GitHub_Trending/ec/ecaptureeCapture 通过--ecaptureq参数将 eBPF 采集到的 TLS/HTTP 事件与运行时日志以 WebSocket ProtobufLogEntry的形式推送到远端但这些二进制消息无法直接肉眼看。本仓库utils/protobuf_visualizer/目录下的 Protobuf Debuggerpb_debugger正是为此设计的终端调试工具连接 eCaptureQ 服务端实时解码并可视化Event、Heartbeat、Log三类 Protobuf 消息。读完本文你将掌握该工具从编译、参数配置到与 eCapture 联调的完整流程并理解其消息分发、Payload 渲染策略背后的源码实现。工具定位与适用场景eCapture 的事件/日志输出有三种通道详见 docs/event-forward-api.md--logaddr输出 eCapture 自身运行时日志纯文本--eventaddr输出捕获事件纯文本--ecaptureq启动 WebSocket 服务端eCaptureQ以结构化LogEntryProtobuf 消息同时流式推送运行时日志与捕获事件。pb_debugger是第三条通道的人肉解码器典型用途包括验证 eCaptureQ 服务端是否正常启动、端口是否可达排查下游集成方如 examples/ecaptureq_client 类客户端收不到消息的问题——先用调试器确认服务端确实在推数据高频事件流下快速浏览每条事件的 PID、五元组与 Payload 内容配合紧凑模式抓取原始 Payload 字节做十六进制比对配合 hex 模式。消息协议基础一切皆 LogEntry调试器对端收到的每一帧 WebSocket 消息都是同一个顶层消息 LogEntryenum LogType { LOG_TYPE_HEARTBEAT 0; LOG_TYPE_PROCESS_LOG 1; LOG_TYPE_EVENT 2; } message LogEntry { LogType log_type 1; oneof payload { Event event_payload 2; Heartbeat heartbeat_payload 3; string run_log 4; } }三个分支分别对应Event捕获的业务事件字段包括timestamp、uuid、src_ip/src_port、dst_ip/dst_port、pid、pname、type、length、payloadHeartbeat心跳字段为timestamp、count、messagerun_logeCapture 进程自身的运行时日志文本。对应的 Go 生成代码位于 protobuf/gen/v1/ecaptureq.pb.goprotoc-gen-go v1.36.6 生成调试器直接 import 该包进行解码与 eCaptureQ 服务端pkg/ecaptureq/server.go 中WriteLog/WriteEvent的编码逻辑使用同一套结构因此字段语义天然一致。编译pb_debugger.go位于仓库根模块github.com/gojue/ecapture见 go.mod之下依赖golang.org/x/net/websocket与google.golang.org/protobuf两个依赖均已在根 go.mod 中声明。进入工具目录后执行cd utils/protobuf_visualizer go build -o pb_debugger pb_debugger.go注意pb_debugger.go是package main单独指定该文件构建即可不会把仓库其他 main 包一并编入。使用常用命令以下命令完整继承自 utils/protobuf_visualizer/README.md中文版见 README_CN.md# 连接默认地址 (ws://127.0.0.1:28257) ./pb_debugger # 指定 WebSocket 服务器地址 ./pb_debugger -url ws://192.168.1.100:28257 # 紧凑模式 (单行输出适合高频数据) ./pb_debugger -compact # 十六进制模式 (查看原始 Payload 字节) ./pb_debugger -hex # 将输出保存到文件自动禁用颜色 ./pb_debugger -no-color capture.log命令行参数全解参数定义见 pb_debugger.go 中的flag注册块参数默认值说明-urlws://127.0.0.1:28257WebSocket 服务端地址-compactfalse启用单行紧凑输出模式-hexfalse以 Hex 格式显示 Payload-max-payload1024限制 Payload 显示的最大字节数-no-colorfalse禁用终端彩色输出源码层面的两点补充说明-max-payload只截断显示不截断数据在 visualizePayload 中当 Payload 超过该阈值时打印一条 Large payload (showing first N of M bytes) 提示并将本地副本截断至max-payload字节原始消息本身已完整解码不受影响。调大该值如-max-payload 8192可看更长报文头调小如-max-payload 128可减少终端刷屏。-no-color与重定向颜色开关只是显式的将输出重定向到文件时建议显式加-no-color避免 ANSI 转义码混入日志文件。源码级工作机制连接与消息接收NewProtobufVisualizer 通过websocket.Dial(url, , http://localhost/)发起握手随后 Listen 进入死循环每收到一帧字节就调用proto.Unmarshal解码为pb.LogEntry失败则打日志并继续等待下一帧——这意味着非 Protobuf 帧不会导致工具退出具备一定容错性。连接断开时websocket.Message.Receive返回错误main中打印 connection closed 并进入退出流程。类型分发一个 switch 覆盖三种消息visualizeLogEntry 按log_type字段 switch 分发并各自维护独立计数器LOG_TYPE_HEARTBEAT→ visualizeHeartbeat展示序列号、时间戳本地时间格式化、心跳计数与消息文本LOG_TYPE_PROCESS_LOG→ visualizeProcessLog原样打印 eCapture 运行时日志行LOG_TYPE_EVENT→ visualizeEvent分四个区块渲染——Metadata序列号/时间戳/UUID、ProcessPID/pname、Networksrc_ip:src_port → dst_ip:dst_port仅当非本地回环时显示、Event Detailstype/length与 Payload。其中事件类型名的映射逻辑在 getEventTypeName0显示为 Send/Write1显示为 Receive/Read其余为 Unknown。Payload 渲染策略visualizePayload 根据开关和数据特征选择三种呈现方式-hex开启输出标准hex.Dump结果偏移 十六进制 可打印字符列适合排查二进制协议字节默认 可打印isPrintable 统计可打印字符ASCII 32~126 及\n\r\t占比超过 80% 判定为文本按行原样打印——抓 HTTP 明文时通常走这条路径默认 二进制取前 64 字节做可打印字符原样、其余替换为·的预览并提示 use --hex flag to see full hexdump。紧凑模式与退出统计-compact模式下不打印横幅头printHeader 直接返回每类消息压缩为一行例如事件行形如[15:04:05] EVENT #12 PID:1234 10.0.0.5:52314 → 1.1.1.1:443 [2048 bytes]适合接grep/管道做高频流分析。非紧凑模式下工具退出CtrlC时会通过 printStats 打印本次会话收到的 Events/Heartbeats/Logs 总数可用于快速核对事件是否完整送达。与 eCapture 联调先启动 eCaptureQ调试器本身只是客户端需先让 eCapture 开启 eCaptureQ 服务端。根据 docs/event-forward-api.md 的说明默认监听地址即调试器默认的ws://127.0.0.1:28257完整联调流程# 1. 启动 eCapture 并开启 eCaptureQ监听 28257 sudo ./ecapture tls --ecaptureqws://127.0.0.1:28257/ # 2. 另开终端编译并启动调试器 cd utils/protobuf_visualizer go build -o pb_debugger pb_debugger.go ./pb_debugger # 3. 高频流量场景紧凑模式 落盘 ./pb_debugger -compact -no-color capture.log服务端行为可对照 pkg/ecaptureq/server.go 源码理解NewServer创建 WebSocket 服务端与广播 Hub每个新客户端注册进 HubWriteLog将日志编码为LogEntry_RunLog并广播同时维护一个容量为LogBuffLen 128的日志缓冲后接入的客户端会先收到缓存的历史日志sendLogBuff因此调试器晚连接也能看到启动阶段的日志WriteEvent将事件字节包进LogEntry_EventPayload自动填充Length后广播。两个排障要点端口不通确认 eCapture 侧确实用了--ecaptureq参数见 cli/cmd/root.go 的参数定义该 flag 非空时才会启动本地 eCaptureQ 服务端并将事件/日志改由其发出若 eCapture 运行在其他机器-url要指向该机器 IP 且 28257 端口未被防火墙拦截。事件不显示但心跳正常说明链路通、eCapture 在跑但当前探针没有抓到目标进程的事件——检查-url对应的 eCapture 实例是否用了对应的探针子命令如tls、以及目标进程是否匹配-p/-c过滤条件。小结pb_debugger用约 400 行 Go 代码实现了一个协议级抓包器以LogEntry的oneof分派为骨架对 Event/Heartbeat/Log 三类消息分别定制渲染并针对高频流场景提供紧凑模式、max-payload截断与 hex 视图。对于集成 eCaptureQ 的开发者和 eCapture 使用者它是验证事件流、核对字段语义、抓取原始 Payload 的第一选择更完整的协议字段语义可继续查阅 protobuf/PROTOCOLS.md 与示例客户端 examples/ecaptureq_client/README.md。【免费下载链接】ecaptureCapturing SSL/TLS plaintext without a CA certificate using eBPF. Supported on Linux/Android kernels for amd64/arm64.项目地址: https://gitcode.com/GitHub_Trending/ec/ecapture创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 eCapture Protobuf Debugger：基于 WebSocket 的 Protobuf 事件流实时可视化调试工具
eCapture Protobuf Debugger基于 WebSocket 的 Protobuf 事件流实时可视化调试工具【免费下载链接】ecaptureCapturing SSL/TLS plaintext without a CA certificate using eBPF. Supported on Linux/Android kernels for amd64/arm64.项目地址: https://gitcode.com/GitHub_Trending/ec/ecaptureeCapture 通过--ecaptureq参数将 eBPF 采集到的 TLS/HTTP 事件与运行时日志以 WebSocket ProtobufLogEntry的形式推送到远端但这些二进制消息无法直接肉眼看。本仓库utils/protobuf_visualizer/目录下的 Protobuf Debuggerpb_debugger正是为此设计的终端调试工具连接 eCaptureQ 服务端实时解码并可视化Event、Heartbeat、Log三类 Protobuf 消息。读完本文你将掌握该工具从编译、参数配置到与 eCapture 联调的完整流程并理解其消息分发、Payload 渲染策略背后的源码实现。工具定位与适用场景eCapture 的事件/日志输出有三种通道详见 docs/event-forward-api.md--logaddr输出 eCapture 自身运行时日志纯文本--eventaddr输出捕获事件纯文本--ecaptureq启动 WebSocket 服务端eCaptureQ以结构化LogEntryProtobuf 消息同时流式推送运行时日志与捕获事件。pb_debugger是第三条通道的人肉解码器典型用途包括验证 eCaptureQ 服务端是否正常启动、端口是否可达排查下游集成方如 examples/ecaptureq_client 类客户端收不到消息的问题——先用调试器确认服务端确实在推数据高频事件流下快速浏览每条事件的 PID、五元组与 Payload 内容配合紧凑模式抓取原始 Payload 字节做十六进制比对配合 hex 模式。消息协议基础一切皆 LogEntry调试器对端收到的每一帧 WebSocket 消息都是同一个顶层消息 LogEntryenum LogType { LOG_TYPE_HEARTBEAT 0; LOG_TYPE_PROCESS_LOG 1; LOG_TYPE_EVENT 2; } message LogEntry { LogType log_type 1; oneof payload { Event event_payload 2; Heartbeat heartbeat_payload 3; string run_log 4; } }三个分支分别对应Event捕获的业务事件字段包括timestamp、uuid、src_ip/src_port、dst_ip/dst_port、pid、pname、type、length、payloadHeartbeat心跳字段为timestamp、count、messagerun_logeCapture 进程自身的运行时日志文本。对应的 Go 生成代码位于 protobuf/gen/v1/ecaptureq.pb.goprotoc-gen-go v1.36.6 生成调试器直接 import 该包进行解码与 eCaptureQ 服务端pkg/ecaptureq/server.go 中WriteLog/WriteEvent的编码逻辑使用同一套结构因此字段语义天然一致。编译pb_debugger.go位于仓库根模块github.com/gojue/ecapture见 go.mod之下依赖golang.org/x/net/websocket与google.golang.org/protobuf两个依赖均已在根 go.mod 中声明。进入工具目录后执行cd utils/protobuf_visualizer go build -o pb_debugger pb_debugger.go注意pb_debugger.go是package main单独指定该文件构建即可不会把仓库其他 main 包一并编入。使用常用命令以下命令完整继承自 utils/protobuf_visualizer/README.md中文版见 README_CN.md# 连接默认地址 (ws://127.0.0.1:28257) ./pb_debugger # 指定 WebSocket 服务器地址 ./pb_debugger -url ws://192.168.1.100:28257 # 紧凑模式 (单行输出适合高频数据) ./pb_debugger -compact # 十六进制模式 (查看原始 Payload 字节) ./pb_debugger -hex # 将输出保存到文件自动禁用颜色 ./pb_debugger -no-color capture.log命令行参数全解参数定义见 pb_debugger.go 中的flag注册块参数默认值说明-urlws://127.0.0.1:28257WebSocket 服务端地址-compactfalse启用单行紧凑输出模式-hexfalse以 Hex 格式显示 Payload-max-payload1024限制 Payload 显示的最大字节数-no-colorfalse禁用终端彩色输出源码层面的两点补充说明-max-payload只截断显示不截断数据在 visualizePayload 中当 Payload 超过该阈值时打印一条 Large payload (showing first N of M bytes) 提示并将本地副本截断至max-payload字节原始消息本身已完整解码不受影响。调大该值如-max-payload 8192可看更长报文头调小如-max-payload 128可减少终端刷屏。-no-color与重定向颜色开关只是显式的将输出重定向到文件时建议显式加-no-color避免 ANSI 转义码混入日志文件。源码级工作机制连接与消息接收NewProtobufVisualizer 通过websocket.Dial(url, , http://localhost/)发起握手随后 Listen 进入死循环每收到一帧字节就调用proto.Unmarshal解码为pb.LogEntry失败则打日志并继续等待下一帧——这意味着非 Protobuf 帧不会导致工具退出具备一定容错性。连接断开时websocket.Message.Receive返回错误main中打印 connection closed 并进入退出流程。类型分发一个 switch 覆盖三种消息visualizeLogEntry 按log_type字段 switch 分发并各自维护独立计数器LOG_TYPE_HEARTBEAT→ visualizeHeartbeat展示序列号、时间戳本地时间格式化、心跳计数与消息文本LOG_TYPE_PROCESS_LOG→ visualizeProcessLog原样打印 eCapture 运行时日志行LOG_TYPE_EVENT→ visualizeEvent分四个区块渲染——Metadata序列号/时间戳/UUID、ProcessPID/pname、Networksrc_ip:src_port → dst_ip:dst_port仅当非本地回环时显示、Event Detailstype/length与 Payload。其中事件类型名的映射逻辑在 getEventTypeName0显示为 Send/Write1显示为 Receive/Read其余为 Unknown。Payload 渲染策略visualizePayload 根据开关和数据特征选择三种呈现方式-hex开启输出标准hex.Dump结果偏移 十六进制 可打印字符列适合排查二进制协议字节默认 可打印isPrintable 统计可打印字符ASCII 32~126 及\n\r\t占比超过 80% 判定为文本按行原样打印——抓 HTTP 明文时通常走这条路径默认 二进制取前 64 字节做可打印字符原样、其余替换为·的预览并提示 use --hex flag to see full hexdump。紧凑模式与退出统计-compact模式下不打印横幅头printHeader 直接返回每类消息压缩为一行例如事件行形如[15:04:05] EVENT #12 PID:1234 10.0.0.5:52314 → 1.1.1.1:443 [2048 bytes]适合接grep/管道做高频流分析。非紧凑模式下工具退出CtrlC时会通过 printStats 打印本次会话收到的 Events/Heartbeats/Logs 总数可用于快速核对事件是否完整送达。与 eCapture 联调先启动 eCaptureQ调试器本身只是客户端需先让 eCapture 开启 eCaptureQ 服务端。根据 docs/event-forward-api.md 的说明默认监听地址即调试器默认的ws://127.0.0.1:28257完整联调流程# 1. 启动 eCapture 并开启 eCaptureQ监听 28257 sudo ./ecapture tls --ecaptureqws://127.0.0.1:28257/ # 2. 另开终端编译并启动调试器 cd utils/protobuf_visualizer go build -o pb_debugger pb_debugger.go ./pb_debugger # 3. 高频流量场景紧凑模式 落盘 ./pb_debugger -compact -no-color capture.log服务端行为可对照 pkg/ecaptureq/server.go 源码理解NewServer创建 WebSocket 服务端与广播 Hub每个新客户端注册进 HubWriteLog将日志编码为LogEntry_RunLog并广播同时维护一个容量为LogBuffLen 128的日志缓冲后接入的客户端会先收到缓存的历史日志sendLogBuff因此调试器晚连接也能看到启动阶段的日志WriteEvent将事件字节包进LogEntry_EventPayload自动填充Length后广播。两个排障要点端口不通确认 eCapture 侧确实用了--ecaptureq参数见 cli/cmd/root.go 的参数定义该 flag 非空时才会启动本地 eCaptureQ 服务端并将事件/日志改由其发出若 eCapture 运行在其他机器-url要指向该机器 IP 且 28257 端口未被防火墙拦截。事件不显示但心跳正常说明链路通、eCapture 在跑但当前探针没有抓到目标进程的事件——检查-url对应的 eCapture 实例是否用了对应的探针子命令如tls、以及目标进程是否匹配-p/-c过滤条件。小结pb_debugger用约 400 行 Go 代码实现了一个协议级抓包器以LogEntry的oneof分派为骨架对 Event/Heartbeat/Log 三类消息分别定制渲染并针对高频流场景提供紧凑模式、max-payload截断与 hex 视图。对于集成 eCaptureQ 的开发者和 eCapture 使用者它是验证事件流、核对字段语义、抓取原始 Payload 的第一选择更完整的协议字段语义可继续查阅 protobuf/PROTOCOLS.md 与示例客户端 examples/ecaptureq_client/README.md。【免费下载链接】ecaptureCapturing SSL/TLS plaintext without a CA certificate using eBPF. Supported on Linux/Android kernels for amd64/arm64.项目地址: https://gitcode.com/GitHub_Trending/ec/ecapture创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考