docs: update docs (#282)

hengyoush · Jan 29, 2025 · 1284a9b · 1284a9b
1 parent 237c9e3
commit 1284a9b
Show file tree

Hide file tree

Showing 10 changed files with 66 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -26,16 +26,20 @@
 
 ## Table of Contents
 
-- [What is kyanos](#-what-is-kyanos)
-- [Examples](#-examples)
-- [Requirements](#-requirements)
-- [How to get kyanos](#-how-to-get-kyanos)
-- [Documentation](#-documentation)
-- [Usage](#-usage)
-- [How to build](#-how-to-build)
-- [Feedback and Contributions](#-feedback-and-contributions)
-- [Special Thanks](#-special-thanks)
-- [Contacts](#%EF%B8%8F-contacts)
+- [kyanos](#kyanos)
+  - [Table of Contents](#table-of-contents)
+  - [What is kyanos](#what-is-kyanos)
+  - [Examples](#examples)
+  - [❗ Requirements](#-requirements)
+  - [🎯 How to get kyanos](#-how-to-get-kyanos)
+  - [📝 Documentation](#-documentation)
+  - [⚙ Usage](#-usage)
+  - [🏠 How to build](#-how-to-build)
+  - [Roadmap](#roadmap)
+  - [🤝 Feedback and Contributions](#-feedback-and-contributions)
+  - [🙇‍ Special Thanks](#-special-thanks)
+  - [🗨️ Contacts](#️-contacts)
+  - [Star History](#star-history)
 
 ## What is kyanos
 
@@ -206,14 +210,12 @@ The Kyanos Roadmap shows the future plans for Kyanos. If you have feature
 requests or want to prioritize a specific feature, please submit an issue on
 GitHub.
 
-_1.5.0_
+_1.6.0_
 
-1. Support for openssl 3.4.0
-2. Support for parsing ipip packets
-3. Support for filtering data based on process name
-4. Support for postgresql protocol parsing
-5. Support for kafka protocol parsing
-6. Full support for ipv6
+1. Support for postgresql protocol parsing.
+2. Support for HTTP2 protocol parsing.
+3. Support for DNS protocol parsing.
+4. Support for GnuTLS.
 
 ## 🤝 Feedback and Contributions
 
@@ -235,7 +237,6 @@ projects:
 
 For more detailed inquiries, you can use the following contact methods:
 
-- **Twitter:** [https://x.com/kyanos_github](https://x.com/kyanos_github)
 - **My Email:** [[email protected]](mailto:[email protected])
 - **My Blog:** [http://blog.deadlock.cloud](http://blog.deadlock.cloud/)
 

diff --git a/README_CN.md b/README_CN.md
@@ -21,16 +21,19 @@
 
 ## Table of Contents
 
-- [What is Kyanos](#-what-is-kyanos)
-- [Examples](#-examples)
-- [Requirements](#-requirements)
-- [How to get kyanos](#-how-to-get-kyanos)
-- [Documentation](#-documentation)
-- [Usage](#-usage)
-- [How to build](#-how-to-build)
-- [Feedback and Contributions](#-feedback-and-contributions)
-- [Special Thanks](#-special-thanks)
-- [Contacts](#%EF%B8%8F-contacts)
+- [Table of Contents](#table-of-contents)
+- [🦜 What is kyanos](#-what-is-kyanos)
+- [🌰 Examples](#-examples)
+- [❗ Requirements](#-requirements)
+- [📝 Documentation](#-documentation)
+- [🎯 How to get kyanos](#-how-to-get-kyanos)
+- [⚙ Usage](#-usage)
+- [🏠 How to Build](#-how-to-build)
+- [Roadmap](#roadmap)
+- [🤝 Feedback and Contributions](#-feedback-and-contributions)
+- [🙇‍ Special Thanks](#-special-thanks)
+- [🗨️ Contacts](#️-contacts)
+- [Star History](#star-history)
 
 ## 🦜 What is kyanos
 
@@ -173,14 +176,12 @@ sudo ./kyanos watch
 
 Kyanos 的 Roadmap 展示了 Kyanos 未来的计划，如果你有功能需求，或者想提高某个特性的优先级，请在 GitHub 上提交 issue。
 
-_1.5.0_
+_1.6.0_
 
-1. 支持 openssl 3.4.0
-2. 支持解析 ipip 包
-3. 支持根据 process name 过滤数据
-4. 支持 postgresql 协议解析
-5. 支持 kafka 协议解析
-6. 完全支持 ipv6
+1. 支持 postgresql 协议解析。
+2. 支持 HTTP2 协议。
+3. 支持 DNS 协议。
+4. 支持 GnuTLS 库解析加密流量。
 
 ## 🤝 Feedback and Contributions
 

diff --git a/docs/cn/faq.md b/docs/cn/faq.md
@@ -53,6 +53,11 @@ https://github.com/aquasecurity/btfhub-archive/
 
 确认你想监控的协议不是 HTTP2，因为 kyanos 目前尚未支持。
 
+## 为什么抓取到的请求数量明显少于真实的请求数量？
+在大流量的情况下 kyanos 可能抓取不到完整的请求数据，检查 `/tmp` 目录下的 kyanos 日志，如果出现 `[dataReader] lost xx syscall data events` 的日志说明正是这种情况。
+
+如果想尽可能的抓取请求可以加上 `--trace-dev-event=false --trace-socket-data` 这个选项，加上该选项后不会抓取数据经过网卡和`socket buffer`的事件，将所有处理能力用于解析 syscall 数据上（目前通过 syscall 数据解析请求和响应）
+
 ## 运行后终端表格颜色不正确（比如无法选择表格中的记录）
 
 ![kyanos missing color](/missing-color.png)

diff --git a/docs/cn/how-to-add-a-new-protocol.md b/docs/cn/how-to-add-a-new-protocol.md
@@ -233,6 +233,8 @@ type ProtocolFilter interface {
 | `FilterByRequest`  | 是否根据请求进行过滤。     |
 | `FilterByResponse` | 是否根据响应进行过滤。     |
 
+另外需要在 `cmd/watch.go` 里的 `supportedProtocols` 需要添加对应的协议名称。
+
 ## Step.5-注册协议解析器
 
 在你写的模块下增加 init 函数，将其写入到 `ParsersMap` 里，例如：
@@ -245,6 +247,8 @@ func init() {
 }
 ```
 
+最后在 `bpf/common.go` 里的 `ProtocolNamesMap` 增加对应的协议名称翻译。
+
 ## Step.6-添加测试
 
 ### 添加 e2e 测试

diff --git a/docs/cn/json-output.md b/docs/cn/json-output.md
@@ -1,4 +1,4 @@
-# JSON 输出格式 <Badge type="tip" text="1.5.0" />
+# JSON 输出格式 <Badge type="tip" text="preview" />
 
 本文档描述了使用 kyanos 的 `--json-output` 参数时的 JSON 输出格式。
 

diff --git a/docs/cn/watch.md b/docs/cn/watch.md
@@ -130,7 +130,7 @@ kyanos 支持根据 IP 端口等三/四层信息过滤，可以指定以下选
 | 请求 Key      | `keys`       | `--keys foo,bar ` 只观察请求 key 为 foo 和 bar        |
 | 请求 key 前缀 | `key-prefix` | `--method foo:bar ` 只观察请求的 key 前缀为 foo\: bar |
 
-#### RocketMQ 协议过滤 <Badge type="tip" text="1.5.0" />
+#### RocketMQ 协议过滤 <Badge type="tip" text="preview" />
 
 | 过滤条件 | 命令行 flag     | 示例                                                                    |
 | :------- | :-------------- | :---------------------------------------------------------------------- |
@@ -144,14 +144,14 @@ kyanos 支持根据 IP 端口等三/四层信息过滤，可以指定以下选
 > [这里](https://github.com/apache/rocketmq/blob/develop/remoting/src/main/java/org/apache/rocketmq/remoting/protocol/LanguageCode.java)。
 
 
-#### Kafka 协议过滤 <Badge type="tip" text="1.5.0" />
+#### Kafka 协议过滤 <Badge type="tip" text="preview" />
 
 | 过滤条件 | 命令行 flag     | 示例                                                                    |
 | :------- | :-------------- | :---------------------------------------------------------------------- |
 | 主题名称 | `topic` | `--topic quickstart-events`                  |
 | 生产者 | `producer` | `--producer` 观察 producer 的请求，指定topic时有用，默认为true                  |
 | 消费者 | `consumer` | `--consumer` 观察 consumer 的请求，指定topic时有用，默认为true                    |
-| 请求代码 | `apikeys` | `--apikeys 10,11` 只观察Kafka APIKEY为 10 和 11 的                    |
+| API Key  | `apikeys` | `--apikeys 10,11` 只观察Kafka APIKEY为 10 和 11 的                    |
 
 > 有关API Key的含义和值，请参阅
 > [这里](https://kafka.apache.org/protocol#protocol_api_keys)。
@@ -168,7 +168,7 @@ kyanos 支持根据 IP 端口等三/四层信息过滤，可以指定以下选
 > 所有上述选项均可以组合使用，比如：`./kyanos watch redis --keys foo,bar --remote-ports 6379 --pid 12345`
 
 
-## JSON 输出 <Badge type="tip" text="1.5.0" />
+## JSON 输出 <Badge type="tip" text="preview" />
 
 如果你需要以编程方式处理采集到的数据，可以使用 `--json-output`
 参数将结果输出为 JSON 格式：

diff --git a/docs/faq.md b/docs/faq.md
@@ -73,6 +73,12 @@ copying to the Socket buffer and being read by the process.
 Make sure the protocol you want to monitor is not HTTP2, as kyanos does not
 currently support it.
 
+## Why is the number of captured requests significantly less than the actual number of requests?
+
+In high-traffic situations, kyanos may not be able to capture complete request data. Check the kyanos logs in the `/tmp` directory. If you see logs like `[dataReader] lost xx syscall data events`, it indicates this situation.
+
+If you want to capture as many requests as possible, you can add the `--trace-dev-event=false --trace-socket-data` option. With this option, events of data passing through the network card and `socket buffer` will not be captured, and all processing power will be used to parse syscall data (currently, requests and responses are parsed through syscall data).
+
 ## Incorrect terminal table colors after running (e.g., unable to select records in the table)
 
 ![kyanos missing color](/missing-color.png)

diff --git a/docs/how-to-add-a-new-protocol.md b/docs/how-to-add-a-new-protocol.md
@@ -272,6 +272,8 @@ type ProtocolFilter interface {
 | `FilterByRequest`  | Filters based on requests.      |
 | `FilterByResponse` | Filters based on responses.     |
 
+Additionally, you need to add the corresponding protocol name to `supportedProtocols` in `watch.go`.
+
 ## Step.5-Register Protocol Parser
 
 Add an init function in your module to write it into the `ParsersMap`, for
@@ -285,6 +287,8 @@ func init() {
 }
 ```
 
+Finally, add the corresponding protocol name translation to `ProtocolNamesMap` in `common.go`
+
 ## Step.6-Add e2e Tests
 
 Add e2e tests for the corresponding protocol in the testdata directory. You can

diff --git a/docs/json-output.md b/docs/json-output.md
@@ -1,4 +1,4 @@
-# JSON Output Format <Badge type="tip" text="1.5.0" />
+# JSON Output Format <Badge type="tip" text="preview" />
 
 This document describes the JSON output format when using kyanos with the
 `--json-output` flag.

diff --git a/docs/watch.md b/docs/watch.md
@@ -148,7 +148,7 @@ Here are the options available for filtering by each protocol:
 | Request Key        | `keys`            | `--keys foo,bar` <br> Only observe requests with the keys `foo` and `bar`.                  |
 | Request Key Prefix | `key-prefix`      | `--key-prefix foo:bar` <br> Only observe requests with keys that have the prefix `foo:bar`. |
 
-#### RocketMQ Protocol Filtering <Badge type="tip" text="1.5.0" />
+#### RocketMQ Protocol Filtering <Badge type="tip" text="preview" />
 
 | Filter Condition | Command Line Flag | Example                                                                                    |
 | ---------------- | ----------------- | ------------------------------------------------------------------------------------------ |
@@ -161,14 +161,14 @@ Here are the options available for filtering by each protocol:
 > For more supported languages, please refer to
 > [here](https://github.com/apache/rocketmq/blob/develop/remoting/src/main/java/org/apache/rocketmq/remoting/protocol/LanguageCode.java).
 
-#### Kafka Protocol Filtering <Badge type="tip" text="1.5.0" />
+#### Kafka Protocol Filtering <Badge type="tip" text="preview" />
 
 | Filter Condition | Command Line Flag | Example |
 | :--------------- | :---------------- | :------ |
 | Topic Name       | `topic`           | `--topic quickstart-events` |
 | Producer         | `producer`        | `--producer` Observe producer requests, useful when specifying a topic, default is true |
 | Consumer         | `consumer`        | `--consumer` Observe consumer requests, useful when specifying a topic, default is true |
-| Request Code     | `apikeys`         | `--apikeys 10,11` Only observe Kafka APIKEYs 10 and 11 |
+| API Keys    | `apikeys`         | `--apikeys 10,11` Only observe Kafka APIKEYs 10 and 11 |
 
 
 > For the meaning and values of API Keys, refer to
@@ -194,7 +194,7 @@ This flexibility allows you to tailor your traffic capture to your specific
 needs, ensuring you gather only the most relevant request-response data.
 
 
-## JSON Output <Badge type="tip" text="1.5.0" />
+## JSON Output <Badge type="tip" text="preview" />
 
 If you need to process the captured data programmatically, you can use the
 `--json-output` flag to output the results in JSON format: