# kyanos: eBPF network analysis that shows where a request actually lost its time

> kyanos is an eBPF-based command line tool that captures HTTP, Redis, MySQL, Kafka, MongoDB, RocketMQ and DNS traffic and breaks each request down by kernel stage. It is for engineers debugging latency on Linux hosts who want more than a packet dump.

**hengyoush/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.

- Repository: https://github.com/hengyoush/kyanos
- Website: https://kyanos.io
- Stars: 5,071 · Forks: 235
- Language: C
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/hengyoush-kyanos

## The gap kyanos fills between tcpdump and an APM agent

Packet capture gives you bytes, not answers. When a Redis call is slow, a pcap tells you packets arrived; it does not tell you whether the delay sat in the process, the network card, or the socket buffer. Installing an APM agent means code changes, a collector, and a backend. kyanos sits in between: one binary, root privilege, and a table of request-response records in the terminal. The README frames the goal as finding the slowest requests and identifying the reasons, and the target user is someone troubleshooting a live Linux host who does not want to go through the capture, download, and analysis cycle.

The filtering is where it diverges from a sniffer. Beyond IP and port, the README shows filters on process id, container id, L7 values such as a Redis key, and response byte size. That last one is the interesting case: you can ask for the largest responses rather than the busiest connections. The stat subcommand aggregates across dimensions instead of dumping packets, so `kyanos stat http --bigresp` is the documented answer to the question of which remote IPs are receiving the biggest responses.

## How kyanos hooks the kernel and what the latency view actually measures

kyanos is written in Go with an eBPF component, and the repository layout reflects that split: a bpf/ directory, a vendored libbpf, a vmlinux/ directory of kernel headers per architecture, and Go packages under cmd/, agent/, monitor/ and common/. The Makefile builds libbpf as a static library, builds bpftool from source, and compiles the BPF objects with clang using the vmlinux headers selected by architecture. The Go side depends on github.com/cilium/ebpf, which is how the compiled programs are loaded and how the maps are read.

The analysis model is the part worth understanding. In the detail view, the README describes a first section called Latency Details where each block is a node the packet passes through (process, network card, socket buffer) and each block carries the time elapsed from the previous node. The chain runs from the process sending the request, to the network card, to the response being copied into the socket buffer, and finally the process reading it. So the number you get is not a single round-trip figure; it is a decomposition. That matters because a 40 ms Redis call that spends 38 ms before the packet leaves the process is a scheduling or application problem, while the same total spent after the response lands in the buffer points somewhere else entirely.

The second section of the detail view shows request and response content in plaintext, and the README states that content over 1024 bytes is truncated. That truncation is a design decision, not an oversight: the tool is built for identifying which request is slow, not for reconstructing a full body. If you need complete payloads, this is the wrong instrument.

## Getting kyanos running and capturing your first HTTP request

There is no package manager step in the README. You download a statically linked binary for amd64 or arm64 from the release page and unpack it. The README gives this exact command:

```bash
tar xvf kyanos_vx.x.x_linux_amd64.tar.gz
```

Replace the version and architecture with the tarball you actually downloaded. After unpacking you have a single binary, which is the whole dependency story the README claims: no agent, no sidecar, no collector.

Check your kernel first, because kyanos supports 3.10 (from 3.10.0-957) and 4.14 or above, with versions between 4.7 and 4.14 listed as future work. Run:

```bash
uname -r
```

If that prints something in the supported range, start with the broadest capture. The README notes kyanos needs root:

```bash
sudo ./kyanos watch
```

The README states that a table appears on success, with each request-response record as a row and the arrow keys or j/k moving between rows. Pressing Enter opens the detail view with the Latency Details section described above. To narrow to one protocol and one path, the documented form is:

```bash
./kyanos watch http --path /abc
```

For the aggregation view, the README's example for finding slow requests over a window is:

```bash
 ./kyanos stat --slow --time 5
```

That reports the slowest requests in the last 5 seconds. If you are chasing bandwidth instead, `kyanos stat http --bigresp` aggregates the largest response byte sizes by remote IP.

## Where kyanos stops being the right tool

The kernel requirement is the first hard boundary. 4.7 through 4.14 is not supported, and the README says support for that range is planned rather than present. On a fleet with mixed kernels, that splits your hosts into two groups and you cannot assume the tool runs everywhere. The README also does not document rollback or uninstall, which is unsurprising for a single binary but worth knowing: you are not installing a service you later remove with a package command.

Root privilege is the second boundary. eBPF programs need it, and the README is explicit that kyanos runs with root privilege. On a managed Kubernetes node or a hardened host where you cannot get that, kyanos is not an option, regardless of how well it fits the problem.

The 1024-byte truncation in the detail view is the third. If the question is what a request body contained, kyanos shows you a prefix. If the question is why the request took 300 ms, the latency decomposition is the point and truncation does not matter.

Finally, scope. kyanos captures HTTP, Redis, MySQL, Kafka, MongoDB, RocketMQ and DNS according to the README. A protocol outside that list is not a filtering problem you can work around; the L7 parsing is not there. For anything unrecognized, tcpdump remains the fallback.

## kyanos against tcpdump and against an APM agent

The README draws the tcpdump comparison itself: tcpdump gives fine-grained packet capture, while kyanos aggregates captured packet metrics across dimensions. The practical difference is the unit of output. tcpdump hands you packets and leaves correlation to you and to whatever you load the pcap into. kyanos hands you request-response rows with a latency breakdown attached, and its filters operate on L7 concepts such as a Redis key or an HTTP path, which tcpdump cannot express because it does not parse the application layer.

Against an APM agent the difference is placement and cost. An APM agent instruments the application and ships data to a backend, which gives you history, cross-service traces, and dashboards, at the price of code or runtime integration and a storage system. kyanos touches nothing in the application, keeps everything in the terminal, and shows you the current state of one host. It has no retention story in the README, so it is not a replacement for tracing. The two answer different questions: an APM tells you this endpoint got slower over the week, kyanos tells you this specific request spent its time here, on this machine, right now.

## Maintenance, licence and what upgrading costs you

The repository is not archived, and the last push was on 2026-09-16. The most recent release listed is v1.6.0 from 2026-06-10, following v1.5.0 in 2025-03-19 and a v1.5.0-rc2 before it. That cadence suggests a project that ships when there is something to ship rather than on a schedule, and the gap between v1.5.0 and v1.6.0 is over a year. Plan upgrades around releases, not around a rolling cadence.

Upgrade cost is low by construction. The README describes a statically linked binary, so an upgrade is replacing a file. There is no agent to restart and no config migration described. The one thing to re-check after an upgrade is kernel compatibility, since the BPF side compiles against per-architecture vmlinux headers and the supported kernel range is a stated constraint rather than an assumption.

kyanos is Apache-2.0. That is a permissive licence, and the repository ships a LICENSE file at the top level. The README also states that some code was borrowed from other projects during development, and the special thanks section in the README is where that attribution lives. If you redistribute kyanos or build it into a product, read the LICENSE and that section rather than assuming a single-source provenance. This is not legal advice; it is a pointer to the files that govern the question.

## Conclusion

Adopt kyanos when you have a Linux host with a 3.10 (from 3.10.0-957) or 4.14+ kernel and need per-request latency plus kernel-stage timing for HTTP, Redis, MySQL, Kafka, MongoDB, RocketMQ or DNS, and you can run it as root. Skip it if you are on a kernel between 4.7 and 4.14, if you need full payload retention (the detail view truncates content over 1024 bytes), or if the machine is a Kubernetes node you cannot grant root on. Before rolling it out, confirm the architecture of your binary against the amd64 or arm64 tarball on the release page, and check that the L7 protocol you care about appears in the watch output on a test host.

## FAQ

### What kernel version does kyanos require?

The README states kyanos supports kernel 3.10 (from 3.10.0-957) and 4.14 or above, with support for versions between 4.7 and 4.14 listed as a future plan. You can check yours with uname -r.

### Which protocols can kyanos capture?

According to the README, kyanos captures HTTP, Redis, MySQL, Kafka, MongoDB, RocketMQ and DNS requests. The simplest command, sudo ./kyanos watch, captures all protocols currently supported.

### Does kyanos need root to run?

Yes. The README says to run kyanos with root privilege, and the quick start uses sudo ./kyanos watch. That follows from the eBPF mechanism it is built on.

### How do I install kyanos?

The README points to the release page for a statically linked binary for amd64 and arm64, unpacked with tar xvf kyanos_vx.x.x_linux_amd64.tar.gz. There is no package manager step documented.

## Sources

- [hengyoush/kyanos on GitHub](https://github.com/hengyoush/kyanos)
- [License: Apache-2.0](https://github.com/hengyoush/kyanos/blob/main/LICENSE)
- [Project website](https://kyanos.io)
- [README](https://github.com/hengyoush/kyanos/blob/main/README.md)
- [Releases](https://github.com/hengyoush/kyanos/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hengyoush-kyanos