KyanoS项目调试指南：从构建到日志分析的完整实践-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01006/article/details/148526917

KyanoS项目调试指南：从构建到日志分析的完整实践

kyanos Kyanos is a networking analysis tool using eBPF. It can visualize the time packets spend in the kernel, capture requests/responses, makes troubleshooting more efficient. 项目地址: https://gitcode.com/gh_mirrors/ky/kyanos

项目概述

KyanoS是一个基于eBPF技术的网络协议分析工具，能够深入内核层面对网络连接和协议进行监控分析。本文将详细介绍KyanoS项目的调试技巧，帮助开发者快速定位和解决问题。

构建相关调试技巧

eBPF代码修改后的特殊处理

在KyanoS项目中，任何对eBPF相关代码的修改都需要特别注意构建顺序：

首先执行make build-bpf命令重新生成bpf相关代码
然后再使用常规的make命令进行构建或在IDE中调试

这种两步构建过程是因为eBPF代码需要先编译成特定的中间格式，然后才能被主程序加载使用。

调试版本构建

为了获得更好的调试体验，建议构建调试版本：

make kyanos-debug

调试版本会包含完整的符号信息和调试信息，便于在IDE中进行单步调试和变量查看。

日志系统深度解析

KyanoS采用了模块化的日志系统，不同功能模块可以独立设置日志级别，极大方便了针对性调试。

日志级别说明

日志级别采用数字表示，其中：

5级为调试级别(DEBUG)
默认级别为警告级别(WARN)

核心日志模块

| 参数名称 | 功能描述 | |------------------------|--------------------------------------------------------------------------| | --agent-log-level | Agent启动相关日志，用于排查初始化问题 | | --bpf-event-log-level | 内核和系统调用层事件日志，涉及底层eBPF程序运行 | | --conntrack-log-level | 连接追踪模块日志，记录连接建立、维护和销毁过程 | | --protocol-log-level | 协议解析日志，详细记录协议识别和解析过程 | | --uprobe-log-level | 用户空间探针日志，主要用于SSL/TLS加解密过程追踪 |

典型调试场景配置

协议解析调试：

--bpf-event-log-level 5 --conntrack-log-level 5 --protocol-log-level 5

eBPF加载问题：
```
--agent-log-level 5
```
控制台输出模式：添加--debug-output参数可将日志输出到标准输出，同时禁用TUI界面显示，适合自动化测试场景。

日志输出示例分析

WARN[0023] [ Request ]
GET /health HTTP/1.1
Host: :8080
User-Agent: Go-http-client/1.1
Accept-Encoding: gzip

[ Response ]
HTTP/1.1 200 OK
Date: Wed, 01 Jan 2025 16:20:20 GMT
Content-Length: 2
Content-Type: text/plain; charset=utf-8

OK

[conn] [pid=2252][local addr]=127.0.0.1:8080 [remote addr]=127.0.0.1:38664 [side]=server [ssl]=false
[total duration] = 0.423(ms)(start=2025-01-02 00:20:20.095, end=2025-01-02 00:20:20.095)
[read from sockbuf]=0.296(ms)
[process internal duration]=0.078(ms)
[syscall] [read count]=1 [read bytes]=92 [write count]=1 [write bytes]=118

这段日志展示了完整的HTTP请求/响应过程，包含了连接信息、时间统计和系统调用详情，是协议分析的黄金数据。

IDE集成开发技巧

VS Code调试配置

在.vscode/launch.json中添加以下配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch file",
      "type": "go",
      "request": "launch",
      "mode": "debug",
      "program": "${workspaceFolder}",
      "args": ["watch", "--debug-output"]
    }
  ]
}

关键点：

必须包含--debug-output参数以便在IDE中查看完整日志
使用watch命令启动可以实时监控网络活动

调试技巧

在协议解析关键函数设置断点
结合日志输出和变量查看进行问题定位
对于并发问题，可以使用条件断点

eBPF层调试高级技巧

内核空间日志输出

在eBPF代码中使用bpf_printk输出调试信息：

bpf_printk("Debug info: value=%d", some_value);

这些日志可以通过dmesg或cat /sys/kernel/debug/tracing/trace_pipe查看。

常见eBPF问题

验证器错误：检查是否有越界访问、循环边界等问题
内存限制：eBPF栈空间有限(512字节)，大数据应使用map存储
兼容性问题：不同内核版本对eBPF特性支持不同

项目代码结构解析

agent/
  analysis/    # 聚合分析模块，stat命令的核心
  conn/        # 连接追踪管理
  protocol/    # 协议解析实现
  render/      # 终端用户界面渲染
  uprobe/      # 用户空间探针(SSL相关)
bpf/
  loader/      # eBPF程序加载逻辑
  pktlatency.bpf.go   # 内核核心代码(系统调用和事件报告)
  gotls.bpf.go        # Go语言TLS探针
  protocol_inference.h # 协议推断算法
  openssl*            # OpenSSL探针相关
cmd/          # 命令行入口
common/       # 通用工具类
docs/         # 项目文档

理解这个结构有助于快速定位问题代码位置。例如：