Kyanos 网络诊断工具全景指南eBPF 驱动的 watch / stat / overview 三大命令实战【免费下载链接】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本文以 Kyanos 官方文档首页docs/index.md对项目的定位描述为主线系统梳理 Kyanos 的核心能力矩阵——七层协议抓包、多维流量过滤、聚合统计分析、容器网络监控与内核级时延可视化并结合仓库中cmd/命令实现与agent/分析模块源码给出可直接落地的命令级实操指南。读完本文你将掌握watch抓包、stat聚合分析与overview依赖洞察三大命令的完整用法并能结合源码理解其底层原理。认识 Kyanos一句话定位与设计哲学Kyanos 是一个基于 eBPF 的网络流量分析工具官方文档首页将其定位为 A Simple Powerful Network Tracing Tool核心价值在于可视化数据包在内核中的耗时并在命令行中完成抓包与分析Visualize the time packets spend in the kernel, watch analyze in command line。在 docs/index.md 首页的 hero 与 feature 卡片中项目官方总结出六大核心特性本文后续章节将逐一展开特性一句话说明对应文档章节 Easy-to-use聚焦七层协议一条命令抓取并分析 HTTP/Redis/MySQL/Kafka/MongoDB/RocketMQ/DNSdocs/how-to.md Advanced Traffic Filtering支持按协议字段如 HTTP Path、Redis Command、PID、容器 ID、K8s Pod 名过滤docs/watch.md Powerful Aggregation Analysis按远端 IP、协议等多维度自动聚合快速得到特定信息docs/stat.md Container Network Monitoring容器化环境下可测量从容器网卡到宿主机网卡的时延docs/watch.md Intuitive TUI纯命令行可视化输出无需 tcpdump 式的文件下载与分析步骤docs/how-to.md Lightweight and Compatible零外部依赖兼容内核 3.10 至最新版本docs/quickstart.md注本仓库docs/目录下同时提供英文与简体中文版本见 README_CN.md中文用户可直接阅读中文文档。为什么需要 Kyanos传统抓包工具的五重痛点官方文档 docs/what-is-kyanos.md 开篇即对比了传统网络排查工具tcpdump、iftop、netstat的局限这些痛点正是 Kyanos 的设计出发点难以按协议信息过滤例如抓取 HTTP 协议中特定 Path 的包tcpdump 无法直接实现需要借助 Wireshark/tshark 二次过滤难以按进程/容器过滤单机多进程或多容器部署时无法只针对特定进程或容器的流量抓包排查效率低典型流程是生产环境 tcpdump 抓包 → 下载 pcap → 本地 Wireshark 分析耗时巨大分析能力有限tcpdump 只提供基础抓包iftop/netstat 只有粗粒度监控难以定位根因无法解密加密流量SSL 等协议请求无法以明文形式查看。而 Kyanos 的应对方案是五件套强大的流量过滤、多维度聚合分析、内核级时延详情、零依赖轻量部署、SSL 流量自动解密。其中 SSL 解密能力在源码中有完整的体系支撑——仓库bpf/目录下包含多个 OpenSSL 版本探针如 openssl_3_4_0.bpf.c、openssl_1_1_1j.bpf.c配合 agent/uprobe/ 模块实现函数级探针注入从而在用户态将 TLS 密文还原为明文。安装与运行环境要求内核版本兼容性根据 docs/quickstart.md 的说明Kyanos 对内核版本的要求按架构区分amd643.x内核版本3.10.0-957 及以上4.x内核版本4.14 及以上5.x、6.x完全支持arm645.5 及以上仓库 README.md 补充说明当前支持内核 3.10自 3.10.0-957 起与 4.14 以上版本并计划未来支持 4.7 至 4.14 之间的版本。可通过uname -r查看当前内核版本。这一兼容性设计的底气来自仓库中的bpf/custom-archive/目录该目录内置了 CentOS 7/8、Ubuntu 18.04/20.04 各内核版本的 BTF 文件如3.10.0-1160.el7.x86_64.btf、5.4.0-91-generic.btf等加上 bpf/btfgen.sh 生成的 btfgen 脚本保证了在缺乏 BTF 的旧内核上也能加载 eBPF 程序。安装步骤从官方 release 页面下载静态链接的二进制兼容 amd64 与 arm64tar xvf kyanos_vx.x.x_linux_amd64.tar.gz然后以root 权限运行sudo ./kyanos watch如果终端出现请求-响应记录表格即表示 Kyanos 启动成功。如果启动失败可参考 docs/faq.md 排查或到 issue 中反馈。核心命令之一watch——抓取请求-响应并查看内核级时延基本用法与界面watch是 Kyanos 最基础的命令负责按指定条件抓取网络流量并自动解析为请求-响应记录docs/how-to.md。最简单的用法是抓取当前支持的所有协议./kyanos watch当前支持解析的协议在 cmd/watch.go 中以supportedProtocols列表形式定义http、redis、mysql、rocketmq、kafka、mongodb、dns。也可用./kyanos watch --list直接查看对应 cmd/watch.go 中的--list标志。执行后每个请求-响应记录以表格行呈现各列含义如下源自 docs/watch.md列名说明示例id表格序号Connection该请求-响应所属连接10.0.4.9:44526 169.254.0.4:80Proto请求-响应使用的协议HTTPTotalTime该请求-响应总耗时毫秒ReqSize请求大小字节RespSize响应大小字节Net/Internal作为客户端时为网络时延作为服务端时为内部处理时间ReadSocketTime客户端从 Socket 缓冲区读取响应耗时服务端为从缓冲区读取请求耗时界面操作方式用↑/↓或k/j键上下移动记录按数字键排序按Enter进入详情视图。默认抓取 100 条记录可用--max-records调整该默认值定义在 cmd/watch.go。详情视图内核级时延可视化详情视图包含三个部分Latency Details时延详情每个块代表数据包经过的一个节点进程、网卡、Socket 缓冲区等块下方标注了从上一节点到该节点的耗时。你可以清晰看到请求从进程发出到网卡、响应从网卡复制到 Socket 缓冲区、再到进程读取的完整过程及各阶段耗时。请求与响应的基本信息包括请求/响应的开始结束时间、大小等。请求与响应的具体内容分为 Request 与 Response 两段超过1024 字节的内容会被截断显示可通过--max-print-bytes调整上限cmd/watch.go。如果想进一步看到网卡到 TCP 缓冲区拷贝与缓冲区到进程读取两个阶段的时延可添加--trace-socket-event选项默认关闭定义于 cmd/watch.go时延图中会额外出现 Socket 块。--trace-dev-event与--trace-ssl-event默认开启分别负责采集网卡设备层事件与 SSL 数据事件cmd/watch.go。多维过滤体系watch最强大的能力在于过滤。所有过滤选项可以自由组合从网络层到协议层逐级收敛流量。按 IP 与端口过滤网络层 L3/L4过滤条件命令行标志示例本地端口--local-ports--local-ports 6379,16379远端端口--remote-ports--remote-ports 6379,16379远端 IP--remote-ips--remote-ips 10.0.4.5,10.0.4.2客户端/服务端--side--side client或--side server这些网络层过滤标志在 cmd/root.go 中作为根命令的持久化标志注册即对所有子命令生效。按进程/容器过滤过滤条件命令行标志示例进程 PID 列表--pids--pids 12345,12346逗号分隔进程名--comm--comm curl容器 ID--container-id--container-id xx容器名--container-name--container-name foobarK8s Pod 名--pod-name--pod-name nginx-7bds23212-23s1s.default格式 NAME.NAMESPACE容器过滤标志同样注册在 cmd/root.go。容器信息获取依赖容器运行时端点支持 Docker、containerd 与 CRI 运行时对应源码为 agent/metadata/container/docker/、agent/metadata/container/containerd/ 与 agent/metadata/k8s/cri.go。值得一提的是在容器化环境中Kyanos 还会展示容器网卡到宿主机网卡之间的时延这正是首页 feature 中 Container Network Monitoring 能力的体现。按请求-响应通用信息过滤过滤条件命令行标志示例请求-响应时延--latency--latency 100只观察超过 100ms 的记录请求大小--req-size--req-size 1024大于 1024 字节响应大小--resp-size--resp-size 1024大于 1024 字节按协议专属字段过滤将协议名作为子命令即可只抓取该协议流量再叠加该协议的专属过滤条件HTTP--path /foo/bar路径精确匹配、--path-prefix /foo/bar路径前缀、--path-regex \/foo\/bar\/.*路径正则、--host www.baidu.comHost、--method GET方法Redis--command GET,SET命令、--keys foo,bar键、--key-prefix foo:bar键前缀RocketMQpreview--request-codes 10,11请求码、--languages Java,Go语言Kafkapreview--topic quickstart-eventsTopic、--producer/--consumer生产/消费方向指定 topic 时默认均为 true、--apikeys 10,11API KeyDNSpreview--host example.com域名MongoDB / MySQL已支持协议抓取条件过滤仍在开发中例如只抓取访问/foo/bar路径的 HTTP 请求kyanos watch http --path /foo/bar组合使用示例来自 docs/watch.md 官方文档./kyanos watch redis --keys foo,bar --remote-ports 6379 --pid 12345JSON 输出preview如果需要程序化处理抓取结果可使用--json-output标志cmd/watch.go# 输出到终端 kyanos watch --json-outputstdout # 输出到文件 kyanos watch --json-output/path/to/custom.json每条请求-响应记录包含请求/响应时间戳、连接详情地址与端口、协议专属信息、详细时延指标、请求与响应内容。完整格式规范见 docs/json-output.md。核心命令之二stat——多维度聚合分析设计动机与基本用法watch的输出是逐条请求-响应的细粒度视图适合底层分析但当需要回答所有服务器都慢还是只有某一台慢哪个客户端 IP 占用了最大带宽这类全局性问题时就需要stat命令对大量请求-响应做聚合统计docs/stat.md。使用stat的核心是明确两件事关心的指标--metric与聚合维度--group-by。例如要分析HTTP 请求慢是所有服务器都慢还是个别服务器慢指标是响应时间、聚合维度是远端 IP./kyanos stat --metric total-time --group-by remote-ip等价于短写形式./kyanos stat -m t -g remote-ip其中-m是--metric的简写、t是total-time的简写、-g是--group-by的简写。命令中--metric、--group-by的解析与校验逻辑位于 cmd/stat.go合法的指标与维度均在源码中有硬编码校验。支持的指标与聚合维度stat当前支持的指标--metric源码见 cmd/stat.go指标短标志长标志总耗时ttotal-time响应大小prespsize请求大小qreqsize网络时延nnetwork-time内部处理时间iinternal-timeSocket 读取耗时ssocket-time源码细节network-time与internal-time在 cmd/stat.go 中均映射到 BlackBoxDuration 指标区别在于前者强制Side ClientSide、后者强制Side ServerSide——这正是 Net/Internal 列客户端看网络、服务端看内部处理语义的源码级来源。stat支持的聚合维度--group-by聚合维度取值按连接conn远端 IPremote-ip远端端口remote-port本地端口local-portL7 协议protocolHTTP 路径http-pathRedis 命令redis-command全部聚合none聚合时还支持二级分组--group-by的值若包含/则/前为主维度、后为子维度cmd/stat.go。另外代码中还针对 HTTP 协议固定启用了HttpPath分类器、针对 Redis 固定启用了RedisCommand分类器cmd/stat.go因此http-path与redis-command维度才能成立。这些分类器Classfier的实现位于 agent/analysis/common/classfier.go 与 agent/analysis/classfier.go。结果解读与下钻stat结果表中除序号外的第二列即为--group-by指定的维度如remote-ip后续列max、avg、p50等表示该维度下聚合记录中指标此处为 total-time的最大值、平均值与 50 分位值。百分位计算实现在 agent/analysis/percentile.go。对某一行按Enter可下钻查看该维度下的具体请求-响应列表视图与watch相同每个记录还可继续Enter查看时延与内容详情。快速分析三件套slow / bigreq / bigresp如果记不住各种选项stat提供了三个快捷模式定义于 cmd/stat.go--slow分析慢请求--bigreq分析大请求--bigresp分析大响应例如快速定位哪个远端 IP 的 HTTP 请求最慢./kyanos stat http --slow找出哪个远端 IP 的请求最大 / 响应最大./kyanos stat http --bigreq ./kyanos stat http --bigresp--time 10可指定采集 10 秒stat默认采集 10 秒可按ctrlc提前结束。注意stat支持watch的全部过滤选项例如./kyanos stat http --slow --path /abc核心命令之三overview——全局依赖洞察beta当需要快速了解一台机器依赖了哪些外部资源及其时延时overview命令一条命令即可完成docs/what-is-kyanos.md 标记为 beta 功能。overview的实现非常简洁cmd/overview.go它本质上复用了stat的分析链路只是强制将聚合维度设置为remote-ip/protocol-adaptive——即按远端 IP 分组、并按协议自适应子分组overview true groupBy remote-ip/protocol-adaptive基本用法sudo kyanos overview可选的--metric标志与stat相同默认t/total-time用于指定统计指标。三大命令的协作关系与适用场景综合 docs/how-to.md 的总结三个子命令形成完整的排查闭环watch按条件抓取流量并解析为请求-响应记录查看详细内容与内核各阶段时延stat在 watch 的基础上对请求-响应做聚合统计回答哪台服务器慢、哪个客户端占带宽等全局问题overview快速盘点整机的外部依赖资源与其时延适合服务治理与容量评估。三者共用同一套过滤选项体系网络层/进程容器层/协议层且均以 TUI 表格呈现、支持数字键排序与 Enter 下钻学习成本可平滑迁移。进一步阅读五步快速上手 docs/how-to.mdwatch 过滤与详情视图完整说明 docs/watch.mdstat 聚合分析完整说明 docs/stat.md安装环境要求与 FAQ docs/quickstart.md、 docs/faq.md从源码编译 COMPILATION.md中文版项目说明 README_CN.md源码入口与命令定义 cmd/root.go、 cmd/watch.go、 cmd/stat.go、 cmd/overview.go【免费下载链接】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），仅供参考