Skip to content

Commit

Permalink
[Doc] Update English doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@hengyoush
hengyoush committed Sep 17, 2024
1 parent c4ff3fa commit 96472be
Show file tree
Hide file tree
Showing 2 changed files with 328 additions and 84 deletions.
176 changes: 92 additions & 84 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
# kyanos
![](docs/banner.png)

[简体中文](./README_CN.md) | English

![GitHub Release](https://img.shields.io/badge/language-golang-blue) ![GitHub Release](https://img.shields.io/badge/os-linux-239120) [![GitHub last commit](https://img.shields.io/github/last-commit/hengyoush/kyanos)](#) [![GitHub release](https://img.shields.io/github/v/release/hengyoush/kyanos)](#) [![Free](https://img.shields.io/badge/free_for_non_commercial_use-brightgreen)](#-license)

⭐ 觉得kyanos还不错？点个star吧~
⭐ Think Kyanos is cool? Give it a star!

[![Share](https://img.shields.io/badge/share-000000?logo=x&logoColor=white)](https://x.com/intent/tweet?text=Check%20out%20this%20project%20on%20GitHub:%20https://github.com/hengyoush/kyanos%20%23OpenIDConnect%20%23Security%20%23Authentication)
[![Share](https://img.shields.io/badge/share-1877F2?logo=facebook&logoColor=white)](https://www.facebook.com/sharer/sharer.php?u=https://github.com/hengyoush/kyanos)
Expand All @@ -22,53 +24,55 @@

## 🚀 Motivation

> 你有没有遇到过这样的问题：
你负责一个业务服务，突然有一天客户端气势汹汹地找你😡，问你的接口为什么调用超时?
你慌了😩但强作镇定查看监控，发现自己服务的接口*耗时正常*
在你刚想回怼他之前你突然想到公司的监控 **仅能监控到服务端应用的耗时, 可中间内核和网络的耗时没有监控**！ 于是你们谁也说服不了谁👿, 接下来开始互相扯皮甩锅，最后问题不了了之
> Have you ever faced this situation:
You're responsible for a service, and one day, an angry client storms over 😡, asking why your API is timing out?
You panic 😩 but try to remain calm as you check the monitoring, only to find that your service's API response time is normal.
Just as you're about to fire back, you suddenly remember that your company's monitoring only tracks the server-side application response time, but not the delays caused by the kernel or network! Now, neither of you can convince the other 👿, and what follows is a long blame game, ultimately with no resolution.

> 反过来，你调用下游接口超时，但对方监控显示并没有超时，于是又开始新的扯皮流程，不同的是你站在了另一边...
> On the flip side, when your request to a downstream API times out but their monitoring shows no issues, the blame game starts again—except this time, you're on the other side...
🤓👍然而当你使用了kyanos，一行命令就可以获取到这个机器上最慢的几个HTTP请求:
🤓👍However, with Kyanos, a single command allows you to retrieve the slowest HTTP requests on this machine:
![](docs/kyanos-demo-1.gif)

如果你需要打印请求响应体，你可以这样：
If you need to print the request and response body, you can do it like this:
![](docs/kyanos-demo-2.gif)


## 🎓 What is kyanos

kyanos正是为了快速排查这类问题诞生的，它是一个**面向程序员**的网络问题分析工具，它有如下优势💪：
- 😏 使用简单, 人性化: 和其他网络分析工具不同，它站在请求响应的视角而不是单个数据报文, 不需要人肉分辨你抓的包哪些是请求哪些是响应, `kyanos` 会自动匹配好.
- 🏎 超级灵活: `kyanos` 以每个请求响应为基础, 统计每次请求响应的耗时, 报文大小, 并且根据需要可以聚合到更高的维度, 使用起来很灵活, 你可以很方便的用一行命令实现诸如: 统计所有 `HTTP` 请求响应最慢的Top5记录, 并且打印请求响应报文!
- 🔎 深入内核采集, 不再有盲区: `kyanos` 基于 `eBPF` 技术, 可以采集到每个请求响应的数据包在内核协议栈中的详细耗时. 最有帮助的耗时如: 1. 请求/响应到达网卡的耗时 2. 数据从socket缓冲区读取的耗时 `kyanos` 都帮你采集好了。
- 自动解析L7协议报文🕹: `kyanos` 目前支持 `HTTP` , `Redis` 和 `MySQL` 这三种业务开开发最常用到的协议报文解析, 后续会支持更多协议.
Kyanos was created specifically for rapid network troubleshooting. It is a **developer-focused** network issue analysis tool with the following features💪：
- 😏 Simple and user-friendly: Unlike other network analysis tools, it focuses on the request-response perspective rather than individual packets. There's no need to manually figure out which captured packets are requests and which are responses—`kyanos` automatically matches them for you.
- 🏎 Highly flexible: `kyanos` is based on each request-response pair, tracking the time taken and the packet size for each interaction. It can also aggregate data to higher levels as needed, making it extremely flexible to use. With just one command, you can easily do things like: find the top 5 slowest `HTTP` request-response pairs and print the corresponding request and response bodies!
- 🔎 Deep kernel-level data collection, no more blind spots: `kyanos` is built on `eBPF` technology, enabling it to capture detailed timings for each request-response packet within the kernel's protocol stack. The most useful timing data, such as 1. the time it takes for requests/responses to reach the network card and 2. the time spent reading data from the socket buffer, are all automatically collected by `kyanos`.
- ⚙ Excellent compatibility: `kyanos` supports kernels as early as version 3.10.

## ❗ Requirements

Kyanos当前支持3.10及4.14以上版本内核(4.7版本到4.14版本之间的后续计划支持)。
> 通过`uname -r`查看内核版本
Kyanos currently supports kernel versions 3.10 and 4.14 or above (with plans to support versions between 4.7 and 4.14 in the future).
> You can check your kernel version using `uname -r`.
At the moment, running Kyanos inside a container requires privileged mode.

## 🎯 How to get kyanos
执行如下脚本获取kyanos可执行文件
To fetch the latest Kyanos executable file, you can use the following script:
```bash
wget -O kyanos.zip https://github.com/hengyoush/kyanos/releases/download/v1.1.0/kyanos.zip
wget -O kyanos.zip https://github.com/hengyoush/kyanos/releases/download/v1.3.0/kyanos.zip
unzip kyanos.zip
chmod a+x kyanos

sudo kyanos
```

## 📝 Usage

kyanos目前有两个主要功能：
Kyanos currently has two main features:

1. watch: 用于观察每个请求响应的：请求响应体 + 耗时情况（包含总耗时，网络耗时，从Socket缓冲区读取耗时等） + 请求响应大小
2. stat：区别于watch的细粒度，stat可以自定义聚合条件，观察更高维度的信息，比如：一个连接上的耗时情况（包括平均耗时，P99线等），请求大小等。
1. **watch**: Used to monitor each request-response pair, including: request and response bodies, timing information (such as total time, network time, and time spent reading from the socket buffer), and request and response sizes.
2. **stat**: Unlike `watch`, which is more granular, `stat` allows for custom aggregation conditions to observe higher-level information, such as: timing details for a connection (including average time, P99 line, etc.), request sizes, and more.

### 🔍 Watch

用法：
Usage：

```bash
./kyanos watch --help
Expand Down Expand Up @@ -101,56 +105,57 @@ Global Flags:
-v, --verbose print verbose message
```

作为最基本的能力，kyanos支持多种协议的流量抓取（目前支持HTTP、Redis、MySQL），同时支持根据响应大小/响应耗时/应用层协议以及应用层协议特定的条件（比如HTTP的Path、Method等）过滤。
As a fundamental capability, Kyanos supports traffic capture for multiple protocols (currently supporting HTTP, Redis, MySQL). It also supports filtering based on response size, response time, application layer protocols, and specific conditions related to those protocols (such as HTTP path, method, etc.).

支持通用过滤条件（协议无关）如下：
Supports the following general (protocol-independent) filtering conditions:

| 过滤条件 | 命令行flag | 示例 |
| :------ | :------------- | :-------------------------------------------------------------------- |
| 请求响应耗时 | --latency | `--latency 100` 只观察耗时超过100ms的请求响应 |
| 请求大小字节数 | --req-size | `--req-size 1024` 只观察请求大小超过1024bytes的请求响应 |
| 响应大小字节数 | --resp-size | `--resp-size 1024` 只观察响应大小超过1024bytes的请求响应 |
| 连接的本地端口 | --local-ports | `--local-ports 6379,16379` 只观察本地端口为6379和16379的连接上的请求响应 |
| 连接的远程端口 | --remote-ports | `--remote-ports 6379,16379` 只观察远程端口为6379和16379的连接上的请求响应 |
| 连接的远程ip | --remote-ips | `--remote-ips 10.0.4.5,10.0.4.2` 只观察远程ip为10.0.4.5和10.0.4.2的连接上的请求响应 |
| 进程pid | --pid | `--pid 12345` 只观察本地进程12345相关的连接 |
| Filter Condition | Command Line Flag | Example |
|--------------------------|-------------------|---------------------------------------------------------------------------------------------|
| Request-Response Latency | `--latency` | `--latency 100` Only observe request-response pairs with latency exceeding 100ms. |
| Request Size in Bytes | `--req-size` | `--req-size 1024` Only observe request-response pairs with request size exceeding 1024 bytes. |
| Response Size in Bytes | `--resp-size` | `--resp-size 1024` Only observe request-response pairs with response size exceeding 1024 bytes. |
| Local Port of Connection | `--local-ports` | `--local-ports 6379,16379` Only observe request-response pairs on connections with local ports 6379 and 16379. |
| Remote Port of Connection| `--remote-ports` | `--remote-ports 6379,16379` Only observe request-response pairs on connections with remote ports 6379 and 16379. |
| Remote IP of Connection | `--remote-ips` | `--remote-ips 10.0.4.5,10.0.4.2` Only observe request-response pairs on connections with remote IPs 10.0.4.5 and 10.0.4.2. |
| Process PID | `--pid` | `--pid 12345` Only observe request-response pairs related to local process 12345. |

支持协议及其过滤条件如下：
Supports the following protocols and their respective filtering conditions:

#### HTTP

| 过滤条件 | 命令行flag | 示例 |
| :----- | :------- | :----------------------------------------------- |
| 请求Path | --path | `--path /foo/bar ` 只观察请求path为/foo/bar |
| 请求Host | --host | `--host www.baidu.com ` 只观察请求Host为www\.baidu.com |
| 请求方法 | --method | `--method GET` 只观察请求为GET |
| Filter Condition | Command Line Flag | Example |
|------------------|-------------------|----------------------------------------------------------------|
| Request Path | `--path` | `--path /foo/bar` Only observe requests with the path `/foo/bar`. |
| Request Host | `--host` | `--host www.baidu.com` Only observe requests with the host `www.baidu.com`. |
| Request Method | `--method` | `--method GET` Only observe requests with the method `GET`. |

#### Redis

| 过滤条件 | 命令行flag | 示例 |
| :------ | :----------- | :---------------------------------------- |
| 请求命令 | --command | `--command GET,SET `只观察请求命令为GET和SET |
| 请求Key | --keys | `--keys foo,bar `只观察请求key为foo和bar |
| 请求key前缀 | --key-prefix | `--method foo:bar ` 只观察请求的key前缀为foo\:bar |
| Filter Condition | Command Line Flag | Example |
|------------------|-------------------|-------------------------------------------------------------|
| Request Command | `--command` | `--command GET,SET` Only observe requests with commands `GET` and `SET`. |
| Request Key | `--keys` | `--keys foo,bar` Only observe requests with keys `foo` and `bar`. |
| Request Key Prefix | `--key-prefix` | `--key-prefix foo:bar` Only observe requests with key prefix `foo:bar`. |

MYSQL

> 已支持MySQL协议抓取，根据条件过滤仍在实现中...
> MySQL protocol capture is supported, but filtering based on conditions is still in progress...

### 📈 Stat

仅有这些只能提供一个细粒度分析的视角，Stat则提供了更为灵活和高维度的分析能力。
它能做的事情很灵活比如：
These features only provide a granular analysis perspective. `Stat` offers more flexible and high-dimensional analysis capabilities. It can do things such as:

- 每5秒输出请求响应在网络中的耗时最长的前10个HTTP连接：`./kyanos stat http --side client -i 5 -m n -l 10 -g conn`
![](docs/kyanos-demo-3.png)
- 每5秒按输出响应大小最大的前10个HTTP请求响应: `./kyanos stat http --side client -i 5 -m p -s 10 -g none`
![](docs/kyanos-demo-4.png)
- 输出所有请求Redis集群的最慢的10个请求：`./kyanos stat redis --side client --remote-ports 6379 -m t -s 10 -g none --full-body`
![](docs/kyanos-demo-5.png)
- Output the top 10 HTTP connections with the longest network latency every 5 seconds: `./kyanos stat http --side client -i 5 -m n -l 10 -g conn`
![](docs/kyanos-demo-3.png)

- Output the top 10 HTTP request-response pairs with the largest response sizes every 5 seconds: `./kyanos stat http --side client -i 5 -m p -s 10 -g none`
![](docs/kyanos-demo-4.png)

- Output the 10 slowest Redis requests to the cluster: `./kyanos stat redis --side client --remote-ports 6379 -m t -s 10 -g none --full-body`
![](docs/kyanos-demo-5.png)

下面介绍具体用法.
Here's a detailed explanation of how to use the commands.
```bash
./kyanos stat --help
Analysis connections statistics
Expand Down Expand Up @@ -187,47 +192,50 @@ Global Flags:
--remote-ports strings specify remote ports to trace, default trace all
-v, --verbose print verbose message
```
### 观测指标(-m)
stat 可以观测 5种指标，分别是：
| 观测指标 | flag |
| :-------------- | :--- |
| 总耗时 | t |
| 响应数据大小 | p |
| 请求数据大小 | q |
| 在网络中的耗时 | n |
| 从Socket缓冲区读取的耗时 | s |

你可以自由组合它们，比如：`-m pq`代表观测请求和响应的大小两个指标：
### Observation Metrics (`-m`)

The `stat` command can observe 5 different metrics, as follows:

| Metric | Flag |
|----------------------|------|
| Total Time | `t` |
| Response Size | `p` |
| Request Size | `q` |
| Network Latency | `n` |
| Time from Socket Buffer | `s` |

You can freely combine these metrics. For example, `-m pq` will observe both request and response sizes:
![](docs/kyanos-demo-6.jpg)

### 聚合维度(-g)
-g选项用于指定将请求响应分类聚合，比如我们关注不同远程服务提供的服务质量是否有差异，就可以指定-g remote-ip，这样请求响应的统计信息就会按照不同的远程ip地址聚合，最终我们将会得到一个不同远程ip的耗时情况，更容易看出哪个远程服务存在问题。
### Aggregation Dimensions (`-g`)

The `-g` option specifies how request-response data should be categorized and aggregated. For example, if you want to analyze the quality of service provided by different remote services, you can use `-g remote-ip` to aggregate statistics by remote IP addresses. This will allow you to see the latency for different remote IPs and easily identify which remote service may be causing issues.

聚合维度目前支持5种，全部是协议无关的(后续会支持协议相关的比如按照HTTP的Path聚合)。
Currently, there are 5 aggregation dimensions, all of which are protocol-independent (protocol-specific dimensions, such as HTTP path aggregation, will be supported in the future).

| 聚合维度 | 值 |
| :-------------- | :--- |
| 最细的粒度，只聚合到单个连接 | conn |
| 远程ip | remote-ip |
| 远程端口 | remote-port |
| 本地端口 | local-port |
| 连接协议 | protocol |
| 最粗粒度，聚合所有的请求响应 | none |
| Aggregation Dimension | Value |
|-----------------------|-------------|
| Finest granularity, aggregates to individual connections | `conn` |
| Remote IP | `remote-ip` |
| Remote Port | `remote-port` |
| Local Port | `local-port` |
| Connection Protocol | `protocol` |
| Coarsest granularity, aggregates all request-response pairs | `none` |

### 输出样本
当我们发现了某些连接的耗时非常高，这时如果能查看这个连接上耗时最高的请求响应就非常有帮助了！
kyanos提供了--sample(-s)参数指定每个聚合的维度可以附加指定个数个样本。
### Output Samples

full-body选项可以指定是否需要打印样本的请求响应，默认是只打印请求响应的概要信息。
When you identify connections with very high latency, it can be very helpful to see the request-response pairs with the highest latency on those connections. Kyanos provides the `--sample` (`-s`) parameter to specify the number of samples to include for each aggregation dimension.

The `full-body` option allows you to specify whether to print the full request and response bodies or just the summary information. By default, only summary information is printed.


## 🤝 Feedback and Contributions
> [!IMPORTANT]
> 这个项目才刚刚诞生，如果你遇到了任何使用上的问题、bug都可以在issue中提问。
> If you encounter any issues or bugs while using the tool, please feel free to ask questions in the issue tracker.
## 🗨️ Contacts
如果你有更详细的问题需要咨询，可以用以下联系方式：
- **我的邮箱：**: [[email protected]](mailto:[email protected]).
- **我的Blog：**: [http://blog.deadlock.cloud](http://blog.deadlock.cloud/).
- **我的微信**：![](docs/wechat.jpg)
For more detailed inquiries, you can use the following contact methods:
- **My Email:** [[email protected]](mailto:[email protected])
- **My Blog:** [http://blog.deadlock.cloud](http://blog.deadlock.cloud/)

[Back to top](#top)
Loading

0 comments on commit 96472be

Please sign in to comment.