日志与追踪上下文
1MCP 使用本地日志记录启动、连接、配置变更和请求失败。它还会转发 MCP 客户端提供的有效追踪上下文,便于在支持追踪的服务器之间关联同一操作。正常使用无需配置追踪。
选择日志输出位置
默认日志级别为 info。排查问题时可使用 debug,并通过 --log-file 保存本地日志:
1mcp serve --log-level debug --log-file ./1mcp.log也可使用环境变量 ONE_MCP_LOG_LEVEL 和 ONE_MCP_LOG_FILE。支持的日志级别为 debug、info、warn 和 error。
HTTP 模式将日志输出到控制台,并在配置文件路径后同时写入文件。Stdio 模式会关闭运行时控制台日志,避免干扰 MCP 通信;需要查看日志时请配置文件。后台模式在未指定日志文件时,默认写入 <config-dir>/logs/server.log。后台运行方式见 serve 命令,日志选项见配置指南。
阅读运行时日志
类型化运行时日志包含时间、级别、固定消息和事件标识。附加字段描述结果、计数或有限的错误类别。其 Debug 事件不包含请求内容或异常堆栈;脱敏后的本地操作和 HTTP 诊断见下文。
部分日志使用指纹代替服务器、会话、客户端或请求标识。同一进程的日志中,同类指纹可用于比较和关联;进程重启后指纹会改变,也不能把指纹用作配置名称或请求 ID。
模板生命周期日志会按需记录 templateName、随机生成的 instanceId、模板或客户端数量以及实例池设置。模板配置名称仅包含字母、数字、点、下划线或连字符且不超过 256 个 UTF-8 字节时,会直接显示;其他名称会被省略。处理模板和解析实例键的事件还包含 templateId_fingerprint,用于关联被省略的名称。渲染配置的哈希和组合实例键可能依赖凭据或会话标识,因此仍使用指纹,不会输出渲染后的配置。
当操作具有有效的入站追踪上下文时,对应运行时日志可包含 trace_id、span_id 和 trace_flags。没有活动追踪上下文的日志不包含这些字段,因此后台生命周期事件等日志可能没有追踪 ID。
查看本地 HTTP 诊断
本地 HTTP 诊断使用 source=http-diagnostic。在 info 级别,http.request、http.response-start 和 http.response 通过生成的 requestId 关联,并按阶段记录接口路径、HTTP 方法、状态码、内容类型、响应字节数、耗时毫秒数和断连结果。发送响应头时就会记录响应开始事件,因此尚未结束的 SSE 连接也可查看。查询参数值以及认证和 Cookie 请求头不会被记录。
解析请求内容后,http.request-context 会在 info 级别记录可识别的 MCP 方法。在 debug 级别,http.request-body 和 http.response-body 会包含脱敏后的业务请求与响应内容。请求内容在认证和后端调用之前记录,便于排查尚未结束的操作;完整的 JSON SSE 数据帧也会被解析并脱敏。凭据字段、OAuth 授权码和 state/PKCE、会话 ID、签名或证明、Cookie 以及可识别的凭据字符串会被隐藏。这些本地诊断记录独立于类型化遥测,不会自动添加追踪字段。
每条脱敏后的序列化内容最多保留 8 KiB,快照最多六层、256 个节点。超大、二进制、压缩、无效 JSON 或不完整的响应使用明确的省略标记。长连接会立即记录响应开始,在结束或断连时记录摘要和内容。Debug 诊断中仍可能保留业务数据,共享日志前请检查其内容。
查看连接与操作诊断
本地操作诊断使用 source=local-diagnostic,在 details 中保留脱敏后的排查信息,补充类型化事件:
| 事件 | 排查信息 |
|---|---|
backend.* | 可安全识别的配置服务器、传输方式、协商版本、连接超时、重试次数和间隔、断连与恢复结果 |
tool.* | 请求和实际选中的后端/工具、本地调用关联标识、阶段、耗时毫秒数、超时、取消、验证失败或上游结果 |
config.* | 配置来源、受影响服务器、新增/删除/修改的字段名和重载结果;不记录配置与环境变量的值 |
schema.*、capability.* | Schema 缓存与加载结果、工具名称、独立加载关联标识、加载数量和失败原因 |
oauth.*、session.* | 授权阶段、可用时的相关后端、成功/失败、会话有效期和数量;不记录原始会话 ID 或授权 URL |
连接与工具失败会保留有界且脱敏的错误消息、错误码和原因链。配置解析失败只记录错误类型,因为解析器消息可能包含配置值。Debug 诊断可包含安全可读的数据属性堆栈和脱敏工具参数/结果;不会执行堆栈访问器或其他调用者 getter,因此没有堆栈不代表没有异常。关闭 Debug 时不会执行工具内容快照回调。
快照同样限制为 8 KiB、六层和 256 个节点。凭据字段及可识别的凭据字符串会被隐藏;凭据 URL 会移除用户信息、查询参数值和片段,错误文本中的 OAuth/会话标识和活动 Runtime Scope 的环境值也会被隐藏。诊断失败不会影响操作。这些记录仅写入本地控制台/文件,不自动添加追踪字段,也不进入类型化遥测或导出链路。脱敏后的 Debug 内容仍可能包含业务数据,共享前请检查。
传递追踪上下文
支持追踪的 MCP 客户端可在请求元数据中提供 W3C 上下文:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {
"_meta": {
"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
}
}1MCP 会向选定后端转发有效的 traceparent 和可选的 tracestate 元数据。相关的服务器到客户端请求及继续请求保留该操作的上下文。无效上下文会被忽略,不会改变授权或服务器选择。HTTP 追踪头不能代替 MCP 请求元数据。
此功能传递已有上下文。1MCP 不创建 Span、不采集指标,也不向收集器导出遥测数据。设置 OTLP 地址不会启用导出,OTEL_SDK_DISABLED=true 也不会关闭消息上下文传播。后端自己的追踪和导出行为由后端配置控制。
隐私与后端诊断
1MCP 类型化运行时事件不包含原始工具参数、响应内容、请求头、URL、路径、错误消息或堆栈。请求和结果中的 _meta.baggage 会被移除,不会转发。工具参数或 structuredContent.baggage 等业务数据中名为 baggage 的字段保持不变。
受管理后端的 stderr 可在 Admin Console 的后端日志工作区中单独查看。这些日志包含经过脱敏的后端诊断内容,具有独立的保留限制,且不会添加 1MCP 追踪关联字段。共享包含后端诊断的日志文件前,请检查其中的内容。
常见问题
- **Stdio 模式没有运行时日志:**配置
--log-file;此模式会关闭运行时控制台日志。 - **日志没有追踪 ID:**检查 MCP 客户端是否发送有效的
params._meta.traceparent。仅发送 HTTP 头不够。 - **收集器中没有追踪数据:**上下文传播不会启用遥测导出。请检查创建 Span 的客户端或后端的追踪配置。
- **错误缺少上游细节:**在 Admin Console 中查看受管理服务器的后端日志,或查看远程后端自己的日志。类型化事件只记录有限的错误信息;本地诊断会保留脱敏后的连接和工具失败细节。
