Add docs for dump streams (#42)

* Add docs for dump streams * feat: en translation --------- Co-authored-by: Toby <[email protected]>
apernet · Nov 12, 2024 · 8ba93f5 · 8ba93f5
1 parent 452f91e
commit 8ba93f5
Show file tree

Hide file tree

Showing 2 changed files with 90 additions and 0 deletions.
diff --git a/docs/docs/advanced/Traffic-Stats-API.md b/docs/docs/advanced/Traffic-Stats-API.md
@@ -57,3 +57,48 @@ Response:
   "joe": 1
 }
 ```
+
+### GET `dump/streams`
+
+This endpoint returns a JSON object containing information about each QUIC stream of a Hysteria TCP proxy connection.
+
+Response:
+
+```json
+{
+  "streams": [
+    {
+      "state": "estab", // (1)!
+      "auth": "user", // (2)!
+      "connection": 3191736581, // (3)!
+      "stream": 4, // (4)!
+      "req_addr": "192.0.2.1:80", // (5)!
+      "hooked_req_addr": "example.com:80", // (6)!
+      "tx": 3937, // (7)!
+      "rx": 4441, // (8)!
+      "initial_at": "2024-11-08T16:07:45.956956773+09:00", // (9)!
+      "last_active_at": "2024-11-08T16:07:47.121503203+09:00" // (10)!
+    }
+  ]
+}
+```
+
+1. Stream state. Refer to [the comment here](https://github.com/apernet/hysteria/blob/3e8c20518db0e97ad67b638e85cbe643b26d777a/core/server/config.go#L223-L257) for their meanings.
+2. The user of this stream.
+3. The ID of the QUIC connection carrying this stream.
+4. The ID of this stream within its QUIC connection.
+5. The address this stream requested to connect to.
+6. The address sniffed from the protocol. If sniffing is not enabled or failed to get an address, this value will be an empty string.
+7. The tx bytes of this stream (upload from the client's perspective).
+8. The rx bytes of this stream (download from the client's perspective).
+9. The time this stream was created.
+10. The time this stream last transmitted data.
+
+When making a request to this API, you can add `Accept: text/plain` to the header to get a human-readable output similar to `ss -atn`.
+
+Response:
+
+```
+State    Auth           Connection   Stream     TX-Bytes     RX-Bytes     Lifetime  Last-Active Req-Addr         Hooked-Req-Addr
+ESTAB    user             BE3E0905        4         3937         4441       3.005s        1.84s 192.0.2.1:80     example.com:80
+```
diff --git a/docs/docs/advanced/Traffic-Stats-API.zh.md b/docs/docs/advanced/Traffic-Stats-API.zh.md
@@ -57,3 +57,48 @@ curl -H 'Authorization: secret' http://ip:port/path
   "joe": 1
 }
 ```
+
+### GET `dump/streams`
+
+此接口返回一个 JSON 对象， 反映当前由 Hysteria 代理的 TCP 流的详细信息。
+
+响应：
+
+```json
+{
+  "streams": [
+    {
+      "state": "estab", // (1)!
+      "auth": "user", // (2)!
+      "connection": 3191736581, // (3)!
+      "stream": 4, // (4)!
+      "req_addr": "192.0.2.1:80", // (5)!
+      "hooked_req_addr": "example.com:80", // (6)!
+      "tx": 3937, // (7)!
+      "rx": 4441, // (8)!
+      "initial_at": "2024-11-08T16:07:45.956956773+09:00", // (9)!
+      "last_active_at": "2024-11-08T16:07:47.121503203+09:00" // (10)!
+    }
+  ]
+}
+```
+
+1. 流状态，请参考 [此处的注释](https://github.com/apernet/hysteria/blob/3e8c20518db0e97ad67b638e85cbe643b26d777a/core/server/config.go#L223-L257) 以了解它们对应的含义。
+2. 使用这个流的用户。
+3. 承载这个流的 QUIC 连接的标识。
+4. 这个流在 QUIC 连接中的标识。
+5. 这个流请求连接到的原始地址。
+6. 协议嗅探出来的地址，如果协议嗅探没有启用或者没有嗅探到地址，则这个值会是空字符串。
+7. 这个流的流量统计信息（客户端角度的上传）。
+8. 这个流的流量统计信息（客户端角度的下载）。
+9. 这个流的创建时间。
+10. 这个流最近一次传输数据的时间。
+
+在请求这个 API 时， 如果在请求头中额外加上 `Accept: text/plain`， 可以获得类似于 `ss -atn` 的人类可读输出。
+
+响应：
+
+```
+State    Auth           Connection   Stream     TX-Bytes     RX-Bytes     Lifetime  Last-Active Req-Addr         Hooked-Req-Addr
+ESTAB    user             BE3E0905        4         3937         4441       3.005s        1.84s 192.0.2.1:80     example.com:80
+```