Kyanos 快速上手指南：基于 eBPF 的网络流量分析工具安装、运行与常见问题排查

Kyanos 快速上手指南基于 eBPF 的网络流量分析工具安装、运行与常见问题排查【免费下载链接】kyanosKyanos 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/GitHub_Trending/ky/kyanosKyanos 是一个基于 eBPF 实现的网络流量分析工具它能够把内核网络路径上的数据包行为从进程系统调用到网卡、再从网卡经 Socket 缓冲区回到进程以请求/响应记录和可视化耗时图的形式呈现出来。本文是 Kyanos 的快速上手教程面向第一次接触该工具的开发者将带你完成环境检查、二进制安装、首次启动验证并系统梳理安装与运行阶段最常见的故障及其解决方案。读完本文你将能够独立把 Kyanos 跑起来、看懂它的交互界面并具备处理 BTF 缺失、容器权限、终端颜色等典型问题的排障能力。安装前的环境检查Kyanos 依赖 eBPF 内核特性因此在安装之前第一步是确认你的内核版本是否满足要求。你可以通过以下命令查看当前内核版本uname -r内核版本要求不同 CPU 架构对内核版本的要求如下源自 docs/quickstart.md 与 README_CN.md 中的声明架构内核要求amd643.x3.10.0-957 及以上amd644.x4.14 及以上amd645.x、6.x完全支持arm645.5 及以上需要说明的是3.10 系列最低支持到3.10.0-957在此之下的内核目前无法运行4.7 到 4.14 之间的内核版本属于后续计划支持范围见 README_CN.md 的 Requirements 一节低版本内核3.x上部分功能可能缺失例如无法按容器 ID/容器名过滤流量也无法自动关联 NAT 前后的流量见 docs/faq.md。从仓库的 bpf/custom-archive 目录可以看到项目为 CentOS 7/8 与 Ubuntu 18.04/20.04 的多个内核版本内置了 BTF 文件如3.10.0-1062.el7.x86_64.btf、4.18.0-147.el8.x86_64.btf、5.4.0-26-generic.btf等。这说明项目对老内核尤其是 CentOS 7 的 3.10 系列做了专门适配Kyanos 在兼容性方面覆盖了相当广的生产环境内核。安装与启动Kyanos 几乎零依赖只需要一个静态链接的二进制文件不需要安装额外的运行时或守护进程所有结果直接展示在命令行中。第一步下载并解压从项目的 Release 页面下载与你的架构amd64 或 arm64匹配的静态链接二进制压缩包然后解压tar xvf kyanos_vx.x.x_linux_amd64.tar.gz如果你使用 arm64 架构则将压缩包名替换为kyanos_vx.x.x_linux_arm64.tar.gz。第二步以 root 权限运行解压后直接以root 权限执行watch命令即可启动默认的流量采集sudo ./kyanos watch需要 root 权限的原因在于Kyanos 需要加载 eBPF 程序、挂载 uprobe/kprobe 探针并读取内核事件这些操作都必须具备特权CAP_BPF / CAP_SYS_ADMIN。这也意味着如果你想在容器或 Pod 中运行 Kyanos必须以privileged特权模式启动容器——这是 docs/faq.md 中明确说明的限制。第三步验证启动成功如果屏幕上出现了类似下面的表格说明 Kyanos 已经成功启动正在实时采集并解析网络请求/响应表格中的每一行代表一条请求-响应记录包含连接信息、协议类型、总耗时、请求/响应大小等关键列。你可以通过方向键↑/↓或j/k上下移动选择记录按Enter进入该条记录的详情视图。详情视图由三部分组成耗时详情每一个方块代表数据包经过的节点进程、网卡、Socket 缓冲区等方块下方的数值表示从上个节点到达该节点所消耗的时间可以直观看到“请求从进程发到网卡、响应从网卡复制到 Socket 缓冲区再被进程读取”的完整链路请求/响应基本信息请求与响应的开始/结束时间、字节大小等请求/响应具体内容分为 Request 与 Response 两部分超过 1024 字节的内容会被截断展示可通过--max-print-bytes调整。如果启动失败不必担心——请阅读下文“常见问题排查”一节看看你的情况是否被覆盖。若不在其中可以通过提交 GitHub Issue 的方式向项目反馈。更精准的抓包过滤与协议选择默认的./kyanos watch会尝试抓取 Kyanos 当前能解析的所有协议流量。目前 Kyanos 支持解析以下 7 种协议对应 cmd/watch.go 中的supportedProtocols定义httpredismysqlrocketmqkafkamongodbdns如果你只想看某种协议的流量把协议名作为子命令传入即可。例如抓取所有 HTTP 流量./kyanos watch http进一步地你可以只关注某个 HTTP Path./kyanos watch http --path /abc也可以组合多种过滤条件所有过滤选项都支持组合使用且遵循“与”逻辑./kyanos watch redis --keys foo,bar --remote-ports 6379 --pids 12345完整的过滤选项IP/端口、进程/容器、耗时/大小、各协议专属字段可以参考 docs/watch.md各协议过滤参数的解析实现可以在 cmd/http.go、cmd/redis.go 等文件中找到。常见问题排查FAQ下面汇总了 Kyanos 安装与运行阶段用户最常遇到的问题及解决方案内容主体继承自 docs/faq.md并补充了源码层面的依据。1. 能在 Windows / Mac 上运行吗目前还不支持但项目有计划在未来支持跟踪于 ISSUE-151。Kyanos 依赖 eBPF而 eBPF 是 Linux 内核特性因此当前只能在 Linux 上运行。2. 低版本内核能否支持支持。最低支持3.10.0-957但低版本内核上部分功能可能缺失3.x 内核不支持按容器 ID/容器名过滤流量3.x 内核无法自动关联 NAT 前后的流量。3. 能在 WSL 里运行吗理论上可以但 WSL 中的 Linux 发行版默认通常不包含 Linux headersKyanos 编译所依赖你可能需要修改编译选项手动编译内核。具体方法可参考 COMPILATION_CN.md 中的编译说明。4. 能在容器 / Pod 中运行吗可以但必须以特权模式privileged运行容器/Pod否则无法加载 eBPF 程序。5. 使用--pod-name时报 can not find any running pod by name xxxKyanos 必须运行在目标 Pod 所在的同一台宿主机上跨节点是无法通过 Pod 名称定位的。6. 运行中出现cant find btf file to load!日志这说明系统缺少与当前内核匹配的 BTF 文件。解决方案有两个手动下载 BTF 文件从公开的 BTF 归档站点下载与内核版本匹配的.btf文件用--btf参数指定启动时通过--btf选项显式指定 BTF 文件路径sudo ./kyanos --btf /path/to/your.btf watch--btf选项在 cmd/root.go 中的定义是specify kernel BTF file。此外仓库的 bpf/custom-archive 目录下内置了大量 CentOS 与 Ubuntu 常见内核版本的 BTF 文件bpf/loader 目录下的 btf.go 实现了 BTF 文件的定位与加载逻辑——从源码结构看Kyanos 会优先尝试使用系统自带的 BTF找不到时才需要手动指定。7. 如何理解 watch 结果中的内核耗时可视化图中每个方块代表数据包经过的一个节点。从上往下解读Process进程表示请求从进程发出eth0if483容器内部网卡设备used:0.02ms表示从进程到容器网卡耗时 0.02mseth0宿主机网卡表示从容器网卡到宿主机网卡耗时 0.02ms请求从网卡发出后经过13.37ms才收到响应图中向下箭头所示随后响应接收过程从右向左展开容器接收响应耗时 0.06ms将响应数据复制到 TCP 缓冲区耗时 0.06ms进程从缓冲区读取数据耗时 0.11ms。通过这张图你可以清楚地看到请求从进程发出到网卡、响应从网卡复制到 Socket 缓冲区再到被进程读取的完整路径与每一环节的耗时从而精准定位“慢”发生在哪一步。小贴士默认情况下耗时图只展示到网卡层。如果你想看到**“数据从网卡复制到 TCP 缓冲区”和“从缓冲区读入进程”**这两段耗时可以给watch命令加上--trace-socket-event选项该选项默认关闭见 cmd/watch.go耗时图中会额外出现一个 Socket 方块。8. 运行后看不到 HTTP 流量请确认你要监控的协议不是 HTTP/2——Kyanos 目前不支持 HTTP/2 协议解析。9. 抓到的请求数量明显少于实际请求数在高流量场景下Kyanos 可能无法捕获完整的请求数据。此时请检查/tmp目录下的 kyanos 日志如果出现[dataReader] lost xx syscall data events之类的日志说明发生了事件丢失。如果希望尽量多抓请求可以关闭网卡层和 Socket 层的事件采集把全部处理能力用于解析 syscall 数据./kyanos watch --trace-dev-eventfalse --trace-socket-data说明--trace-dev-event选项在 cmd/watch.go 中默认值为true用于采集网卡层事件以统计网络接口耗时关闭后不再采集“数据经过网卡与 socket buffer”的事件从而集中资源解析请求/响应本身目前请求和响应是通过 syscall 数据解析的。10. 运行后终端表格颜色显示异常如无法选中表格记录如果启动时出现Your terminal does not support 256 colors, ui may display incorrectly日志说明终端颜色配置不正确——Kyanos 的 UI 需要 256 色终端。先用下面这条命令列出系统支持的所有终端类型及其颜色位数for T in find /usr/share/terminfo -type f -printf %f ;do echo $T tput -T $T colors;done|sort -nk2|tail -n20示例输出Eterm-88color 88 rxvt-88color 88 xterm-88color 88 xterm88color 88 Eterm-256color 256 gnome-256color 256 iTerm.app 256 konsole-256color 256 ...$TERM环境变量表示当前终端类型可用echo $TERM查看。如果当前终端只支持 256 色以下可以修改~/.bashrc加入以下内容后重新加载case $TERM in xterm) export TERMxterm-256color ;; screen) export TERMscreen-256color ;; esac11. 关于--pod-name、容器过滤与运行时端点从 cmd/root.go 可以看到Kyanos 支持按容器 ID--container-id、容器名--container-name、Pod 名--pod-name格式为NAME.NAMESPACE过滤并且可以通过--docker-address、--containerd-address、--cri-runtime-address指定容器运行时端点。容器过滤功能由 agent/metadata 下的 docker/containerd/k8s 模块实现。启动成功之后下一步可以做什么安装验证通过后你可以继续深入 Kyanos 的两大核心能力watch请求-响应与耗时详情抓取。支持 IP/端口、进程/容器、耗时/大小以及各协议专属字段HTTP path、Redis 命令与 key、RocketMQ request-code、Kafka topic 等的多维过滤。更完整的用法参考 docs/watch.md。stat聚合统计分析。将大量请求-响应按指定维度如remote-ip、conn、http-path聚合配合--metrict/total-time、p/respsize、q/reqsize、n/network-time、s/socket-time等与快捷模式--slow、--bigreq、--bigresp快速回答“哪个远端 IP 最慢”“谁占用了最多带宽”这类问题。参考 docs/stat.md 与 cmd/stat.go。overview全局依赖概览。一条命令展示当前机器依赖的外部资源及其延迟适合做全局依赖分析。参考 docs/what-is-kyanos.md 与 cmd/overview.go。如果你希望用 5 分钟快速掌握这三个子命令的基本用法可以直接阅读 docs/how-to.md《Learn Kyanos in 5 Minutes》需要把采集结果接入自动化脚本时可以使用--json-output输出 JSON 格式数据格式规范见 docs/json-output.md。【免费下载链接】kyanosKyanos 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/GitHub_Trending/ky/kyanos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考