拓冰网站定制 
如何启用 MCP Toolbox 的 SQL Commenter 在数据库查询日志中关联 MCP 客户端与分布式追踪【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox当 AI 应用通过 MCP Toolbox 执行数据库工具时数据库端只能看到一条条 SQL无法回答“这条慢查询是谁、哪个模型、哪次调用发起的”。MCP Toolbox 的 SQL Commenter 功能可以在每条 SQL 语句前添加一段 SQLCommenter 格式的结构化注释把traceparent、发起请求的 MCP 客户端client、模型client.model、用户client.user.id、agentclient.agent.id和工具名tool.name等信息带进查询。这段注释会在查询规划前被剥离不影响查询结果但会原样出现在数据库查询日志和慢查询日志中从而把应用层的分布式追踪与数据库层的日志关联起来。本功能默认关闭按数据源启用。下文以 PostgreSQL 数据源为例给出从启用到在日志中核对的完整操作路径。准备条件SQL Commenter 目前仅支持以下数据源类型见 sql_commenter.md 的 “Supported Sources” 一节alloydb-postgresbigquery以 job labels 形式实现而不是 SQL 注释cloud-sql-postgrescloud-sql-mysqlpostgresmysqlsqlite如果你的数据源不在列表中本功能不适用。要完成“关联分布式追踪”这一步还需要 Toolbox 把 traces 导出到某个后端OTLP Collector 或 Google Cloud Monitoring否则traceparent注释虽会写入日志但你没有地方可以检索对应的 trace。导出方式的配置见下文第 3 节。按数据源启用 sqlCommenter在工具配置文件中对目标 source 设置sqlCommenter: true来源为 sql_commenter.mdsources: - name: my-pg-source type: postgres # ... sqlCommenter: true这是按数据源粒度的开关只有设置了该字段的 source 上执行的 SQL 才会被加上注释其余 source 不受影响。此外Telemetry 文档 的 Flags 一节还列出了全局标志--sql-commenterbool默认false可用于对所有执行的 SQL 语句添加 SQLCommenter 格式注释。CLI 参考 同样将其描述为 “Prepend SQLCommenter-format comments (traceparent, server, tool.name, db.system.name, client metadata from_meta[dev.mcp-toolbox/telemetry]) to executed SQL”。按需选择配置文件内的按源开关或命令行全局开关即可。配置遥测导出让 trace 可检索SQL 注释里的traceparent来自当前的 OpenTelemetry span 上下文要在追踪后端里按它检索需要先让 Toolbox 导出 traces。两种方式都记录在 export_telemetry.md 和 telemetry/index.md方式一OTLP Collector安装 OpenTelemetry Collector 二进制并为其配置 traces 管线receivers/processors/exporters加service.pipelines。文档给出的示例配置其中YOUR_GOOGLE_CLOUD_PROJECT为文档中的占位符需替换为你自己的项目 IDreceivers: otlp: protocols: http: endpoint: 127.0.0.1:4553 exporters: googlecloud: project: YOUR_GOOGLE_CLOUD_PROJECT processors: batch: send_batch_size: 200service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [googlecloud]用该配置文件启动 Collector./otelcol-contrib --configcollector-config.yaml启动 Toolbox 时通过--telemetry-otlp指向 Collector 端点./toolbox --telemetry-otlp127.0.0.1:4553端点为明文 HTTP 时文档提示需设置环境变量OTEL_EXPORTER_OTLP_INSECUREtrue。方式二直接导出到 Google Cloud Monitoring启用--telemetry-gcp必要时加--telemetry-gcp-projectmy-project-id不设置时回落到GOOGLE_CLOUD_PROJECT./toolbox --telemetry-gcp --telemetry-gcp-projectmy-project-id使用 GCP Exporter 时运行身份需要roles/monitoring.metricWriter和roles/cloudtrace.agent两个角色文档特别提醒两个信号独立鉴权只授予其中一个会导致“指标正常但每次 trace 导出都失败于PermissionDeniedoncloudtrace.traces.patch”排查时先核对这个角色。可选让 MCP 客户端信息进入注释注释中的server、tool.name、db.system.name由 Toolbox 自身填充client、client.model、client.user.id、client.agent.id则来自 MCP 请求的params._meta[dev.mcp-toolbox/telemetry]字段客户端没提供的属性会直接从注释中省略。使用支持该 meta 字段的 Python SDK 时可以自动填充这些属性来源为 Python SDK core 文档pip install toolbox-core[telemetry]from toolbox_core import ToolboxClient, TelemetryAttributes async with ToolboxClient(http://127.0.0.1:5000, telemetry_enabledTrue) as toolbox: tool await toolbox.load_tool(my-tool) attrs TelemetryAttributes( llm_modelgemini-2.5-pro, user_iduser-123, agent_idagent-abc, ) instrumented_tool tool.add_telemetry_attributes(attrs) result await instrumented_tool(paramvalue)几个文档明确的行为点字段到线上 key 的映射llm_model→client.modeluser_id→client.user.idagent_id→client.agent.id。add_telemetry_attributes()返回一个新工具实例原工具不变重复调用是替换而非合并需要把所有字段放进同一个TelemetryAttributes。未设置的字段和空字符串会在发送前丢弃不会以空值形式出现。telemetry_enabledTrue依赖[telemetry]extra未安装时该标志会被静默忽略。client属性本身来自params._meta[dev.mcp-toolbox/telemetry]中的client.name与client.version以/连接用于标识发起 MCP 请求的 ADK 或应用。验证在数据库日志中确认注释并回溯 trace启用后Toolbox 会对支持的数据源上执行的每条 SQL 前缀一段注释。注释规则键按字母序排列、值做 URL 编码、键值对以逗号连接并包在/* … */块内。下面是源文档给出的示例示例结果实际键值会随你的调用上下文变化/*clienttoolbox-langchain-python%2Fv0.1.0,client.modelgemini-2.5-flash,db.system.namepostgresql,servergenai-toolbox%2F1.1.0,tool.namesearch_user,traceparent00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01*/ SELECT * FROM users WHERE id $1;验证分两步均按文档给出的方法在数据库侧确认注释已写入。检查数据库查询日志PostgreSQL/MySQL 的 query log 或 slow-query log。注释是纯文本直接出现在日志中的 SQL 语句前。按 traceparent 回溯分布式追踪。文档给出的方法是取日志中注释的traceparent值在你的追踪后端里搜索对应的 trace ID——即 W3Ctraceparent的第二段示例中的4bf92f3577b34da6a3ce929d0e0e4736。如果第 1 步的注释存在而第 2 步搜不到 trace优先检查第 3 节的遥测导出配置端点是否可达、OTEL_EXPORTER_OTLP_INSECURE是否设置、GCP 角色是否齐全。各注释键的完整含义见 sql_commenter.md 的 Attributes 表。限制与边界仅限支持的数据源上文列表外的 source 类型不会添加注释BigQuery 的对应实现是 job labels 而非 SQL 注释详见 bigquery source 文档。注释不影响结果注释在查询规划前被剥离对查询结果没有影响它的唯一作用是出现在日志中。属性可缺省客户端未提供或当前上下文不适用的属性会被省略所以不同调用的注释长度和键集合可能不同这属于正常现象不代表配置丢失。默认关闭sqlCommenter/--sql-commenter默认均为false未显式开启时日志中不会出现任何注释。完成上述配置后每条经由 Toolbox 执行的 SQL 都会携带可回溯的上下文慢查询日志条目即可按traceparent直接落到发起它的那次 MCP 调用与客户端上。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何启用 MCP Toolbox 的 SQL Commenter 在数据库查询日志中关联 MCP 客户端与分布式追踪
如何启用 MCP Toolbox 的 SQL Commenter 在数据库查询日志中关联 MCP 客户端与分布式追踪【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox当 AI 应用通过 MCP Toolbox 执行数据库工具时数据库端只能看到一条条 SQL无法回答“这条慢查询是谁、哪个模型、哪次调用发起的”。MCP Toolbox 的 SQL Commenter 功能可以在每条 SQL 语句前添加一段 SQLCommenter 格式的结构化注释把traceparent、发起请求的 MCP 客户端client、模型client.model、用户client.user.id、agentclient.agent.id和工具名tool.name等信息带进查询。这段注释会在查询规划前被剥离不影响查询结果但会原样出现在数据库查询日志和慢查询日志中从而把应用层的分布式追踪与数据库层的日志关联起来。本功能默认关闭按数据源启用。下文以 PostgreSQL 数据源为例给出从启用到在日志中核对的完整操作路径。准备条件SQL Commenter 目前仅支持以下数据源类型见 sql_commenter.md 的 “Supported Sources” 一节alloydb-postgresbigquery以 job labels 形式实现而不是 SQL 注释cloud-sql-postgrescloud-sql-mysqlpostgresmysqlsqlite如果你的数据源不在列表中本功能不适用。要完成“关联分布式追踪”这一步还需要 Toolbox 把 traces 导出到某个后端OTLP Collector 或 Google Cloud Monitoring否则traceparent注释虽会写入日志但你没有地方可以检索对应的 trace。导出方式的配置见下文第 3 节。按数据源启用 sqlCommenter在工具配置文件中对目标 source 设置sqlCommenter: true来源为 sql_commenter.mdsources: - name: my-pg-source type: postgres # ... sqlCommenter: true这是按数据源粒度的开关只有设置了该字段的 source 上执行的 SQL 才会被加上注释其余 source 不受影响。此外Telemetry 文档 的 Flags 一节还列出了全局标志--sql-commenterbool默认false可用于对所有执行的 SQL 语句添加 SQLCommenter 格式注释。CLI 参考 同样将其描述为 “Prepend SQLCommenter-format comments (traceparent, server, tool.name, db.system.name, client metadata from_meta[dev.mcp-toolbox/telemetry]) to executed SQL”。按需选择配置文件内的按源开关或命令行全局开关即可。配置遥测导出让 trace 可检索SQL 注释里的traceparent来自当前的 OpenTelemetry span 上下文要在追踪后端里按它检索需要先让 Toolbox 导出 traces。两种方式都记录在 export_telemetry.md 和 telemetry/index.md方式一OTLP Collector安装 OpenTelemetry Collector 二进制并为其配置 traces 管线receivers/processors/exporters加service.pipelines。文档给出的示例配置其中YOUR_GOOGLE_CLOUD_PROJECT为文档中的占位符需替换为你自己的项目 IDreceivers: otlp: protocols: http: endpoint: 127.0.0.1:4553 exporters: googlecloud: project: YOUR_GOOGLE_CLOUD_PROJECT processors: batch: send_batch_size: 200service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [googlecloud]用该配置文件启动 Collector./otelcol-contrib --configcollector-config.yaml启动 Toolbox 时通过--telemetry-otlp指向 Collector 端点./toolbox --telemetry-otlp127.0.0.1:4553端点为明文 HTTP 时文档提示需设置环境变量OTEL_EXPORTER_OTLP_INSECUREtrue。方式二直接导出到 Google Cloud Monitoring启用--telemetry-gcp必要时加--telemetry-gcp-projectmy-project-id不设置时回落到GOOGLE_CLOUD_PROJECT./toolbox --telemetry-gcp --telemetry-gcp-projectmy-project-id使用 GCP Exporter 时运行身份需要roles/monitoring.metricWriter和roles/cloudtrace.agent两个角色文档特别提醒两个信号独立鉴权只授予其中一个会导致“指标正常但每次 trace 导出都失败于PermissionDeniedoncloudtrace.traces.patch”排查时先核对这个角色。可选让 MCP 客户端信息进入注释注释中的server、tool.name、db.system.name由 Toolbox 自身填充client、client.model、client.user.id、client.agent.id则来自 MCP 请求的params._meta[dev.mcp-toolbox/telemetry]字段客户端没提供的属性会直接从注释中省略。使用支持该 meta 字段的 Python SDK 时可以自动填充这些属性来源为 Python SDK core 文档pip install toolbox-core[telemetry]from toolbox_core import ToolboxClient, TelemetryAttributes async with ToolboxClient(http://127.0.0.1:5000, telemetry_enabledTrue) as toolbox: tool await toolbox.load_tool(my-tool) attrs TelemetryAttributes( llm_modelgemini-2.5-pro, user_iduser-123, agent_idagent-abc, ) instrumented_tool tool.add_telemetry_attributes(attrs) result await instrumented_tool(paramvalue)几个文档明确的行为点字段到线上 key 的映射llm_model→client.modeluser_id→client.user.idagent_id→client.agent.id。add_telemetry_attributes()返回一个新工具实例原工具不变重复调用是替换而非合并需要把所有字段放进同一个TelemetryAttributes。未设置的字段和空字符串会在发送前丢弃不会以空值形式出现。telemetry_enabledTrue依赖[telemetry]extra未安装时该标志会被静默忽略。client属性本身来自params._meta[dev.mcp-toolbox/telemetry]中的client.name与client.version以/连接用于标识发起 MCP 请求的 ADK 或应用。验证在数据库日志中确认注释并回溯 trace启用后Toolbox 会对支持的数据源上执行的每条 SQL 前缀一段注释。注释规则键按字母序排列、值做 URL 编码、键值对以逗号连接并包在/* … */块内。下面是源文档给出的示例示例结果实际键值会随你的调用上下文变化/*clienttoolbox-langchain-python%2Fv0.1.0,client.modelgemini-2.5-flash,db.system.namepostgresql,servergenai-toolbox%2F1.1.0,tool.namesearch_user,traceparent00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01*/ SELECT * FROM users WHERE id $1;验证分两步均按文档给出的方法在数据库侧确认注释已写入。检查数据库查询日志PostgreSQL/MySQL 的 query log 或 slow-query log。注释是纯文本直接出现在日志中的 SQL 语句前。按 traceparent 回溯分布式追踪。文档给出的方法是取日志中注释的traceparent值在你的追踪后端里搜索对应的 trace ID——即 W3Ctraceparent的第二段示例中的4bf92f3577b34da6a3ce929d0e0e4736。如果第 1 步的注释存在而第 2 步搜不到 trace优先检查第 3 节的遥测导出配置端点是否可达、OTEL_EXPORTER_OTLP_INSECURE是否设置、GCP 角色是否齐全。各注释键的完整含义见 sql_commenter.md 的 Attributes 表。限制与边界仅限支持的数据源上文列表外的 source 类型不会添加注释BigQuery 的对应实现是 job labels 而非 SQL 注释详见 bigquery source 文档。注释不影响结果注释在查询规划前被剥离对查询结果没有影响它的唯一作用是出现在日志中。属性可缺省客户端未提供或当前上下文不适用的属性会被省略所以不同调用的注释长度和键集合可能不同这属于正常现象不代表配置丢失。默认关闭sqlCommenter/--sql-commenter默认均为false未显式开启时日志中不会出现任何注释。完成上述配置后每条经由 Toolbox 执行的 SQL 都会携带可回溯的上下文慢查询日志条目即可按traceparent直接落到发起它的那次 MCP 调用与客户端上。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考