From 9994311cad6acc8d09e9e367e92089840a0bcd11 Mon Sep 17 00:00:00 2001 From: Jin Jie Date: Fri, 21 Nov 2025 16:38:08 +0800 Subject: [PATCH] update doc for mysql --- docs/zh/05-features/01-l7-protocols/04-sql.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/zh/05-features/01-l7-protocols/04-sql.md b/docs/zh/05-features/01-l7-protocols/04-sql.md index 52740172..18054cdd 100644 --- a/docs/zh/05-features/01-l7-protocols/04-sql.md +++ b/docs/zh/05-features/01-l7-protocols/04-sql.md @@ -18,7 +18,7 @@ permalink: /features/l7-protocols/sql | | request_id | 请求 ID | Statement ID | Statement ID | 从 `COM_STMT_PREPARE` 响应、`COM_STMT_EXECUTE` 请求中提取 | | | endpoint | 端点 | -- | -- | -- | | Resp. | response_code | 响应码 | -- | Error Code | -- | -| | response_status | 响应状态 | -- | Error Code | 正常: 非 `ERR` 消息; 客户端异常/服务端异常详见 [2] | +| | response_status | 响应状态 | -- | Error Code | 正常: 非 `ERR` 消息；客户端异常/服务端异常详见 [2] | | | response_exception | 响应异常 | -- | Error Message | -- | | | response_result | 响应结果 | -- | -- | -- | | Trace | trace_id | TraceID | SQL Comments | -- | 注释中的 TraceID 支持提取，提取及配置方法详见 [3] | @@ -29,7 +29,7 @@ permalink: /features/l7-protocols/sql - [1] 目前支持解析的命令：`COM_QUERY`、`COM_QUIT`、`COM_INIT_DB`、`COM_FIELD_LIST`、`COM_STMT_PREPARE`、`COM_STMT_EXECUTE`、`COM_STMT_FETCH`、`COM_STMT_CLOSE`。 - [2] 客户端异常：Error Code=2000-2999，或客户端发送 1-999；服务端异常：Error Code=1000-1999/3000-4000，或服务端发送 1-999。 - [3] 当应用在 SQL 语句的注释中注入 TraceID（或复合的 TraceID + SpanID）时，DeepFlow 支持提取并用于跨线程的分布式追踪。DeepFlow 支持提取几乎任意位置的 SQL 注释（但必须出现在 AF_PACKET 获取到的首包中，或者 eBPF 获取到的第一个 Socket Data 中）；注释中的键值对可以用冒号 `:` 和空格 ` ` 分割，也可以用等号 `=` 和逗号 `,` 分割，但注意字段中**不能**包含冒号或等号。 -- [4] 提取 `COM_STMT_EXECUTE` 中的参数不能开启采集器高级配置 `obfuscate-enabled-protocols`; 参数会使用**空格+逗号+空格**（例如 `123 , abc`）拼接赋值给 `request_resource`; 当流量出现乱序、丢包、重传、截断等会导致参数解析错误。 + ```sql /* your_trace_key: 648840f6-7f92-468b-b298-d38f05c541d4 */ SELECT col FROM tbl SELECT /* your_trace_key: 648840f6-7f92-468b-b298-d38f05c541d4 */ col FROM tbl @@ -37,11 +37,17 @@ permalink: /features/l7-protocols/sql SELECT col FROM tbl -- your_trace_key: 648840f6-7f92-468b-b298-d38f05c541d4 SELECT col FROM tbl # your_trace_key=648840f6-7f92-468b-b298-d38f05c541d4 ``` + 虽然如此，我们**强烈建议您在 SQL 语句头部添加注释**，以降低 SQL 解析的性能开销。上面的示例中，`your_trace_key` 取决于 Agent 配置项中 `http_log_trace_id` 的值（但请注意如果使用 traceparent / sw8 / uber-trace-id，请遵循 [OpenTelemetry](https://www.w3.org/TR/trace-context/#traceparent-header-field-values) / [SkyWalking](https://skywalking.apache.org/docs/main/next/en/api/x-process-propagation-headers-v3/) / [Jaeger](https://www.jaegertracing.io/docs/1.54/client-libraries/#tracespan-identity) 的协议规范）。例如当 `http_log_trace_id = traceparent, sw8` 时，DeepFlow 能够从 `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01` 中提取符合 OpenTelemetry 规范的 TraceID 和 SpanID： + ```sql /* traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 */ SELECT col FROM tbl ``` + 此外，Agent（仅企业版）支持从 SQL Insert 语句中提取 TraceID，配置参考[自定义字段提取策略](../../configuration/agent/#processors.request_log.tag_extraction.custom_field_policies)。 + +- [4] 提取 `COM_STMT_EXECUTE` 中的参数不能开启采集器高级配置 `obfuscate-enabled-protocols`；参数会使用**空格+逗号+空格**（例如 `123 , abc`）拼接赋值给 `request_resource`；当流量出现乱序、丢包、重传、截断等会导致参数解析错误。 + 注意，以下为单向消息，会被直接保存为 type=session 的调用日志： - COM_STMT_CLOSE @@ -77,7 +83,7 @@ permalink: /features/l7-protocols/sql | | request_id | 请求 ID | -- | -- | -- | | | endpoint | 端点 | -- | -- | -- | | Resp. | response_code | 响应码 | -- | -- | -- | -| | response_status | 响应状态 | -- | Error Code | 正常: 非 `error return` 消息; 客户端异常/服务端异常详见 [1] | +| | response_status | 响应状态 | -- | Error Code | 正常: 非 `error return` 消息；客户端异常/服务端异常详见 [1] | | | response_exception | 响应异常 | -- | Error Code | Error Code 的[英文描述](https://www.postgresql.org/docs/10/errcodes-appendix.html) | | | response_result | 响应结果 | -- | Error Code | 仅 `error return` 消息 | | Trace | trace_id | TraceID | -- | -- | -- |