日志与追踪上下文

Name: 1MCP Agent
Author: 1MCP

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 级别会增加诊断事件，但不会输出原始请求内容或异常堆栈。

部分日志使用指纹代替服务器、会话、客户端或请求标识。同一进程的日志中，同类指纹可用于比较和关联；进程重启后指纹会改变，也不能把指纹用作配置名称或请求 ID。

当操作具有有效的入站追踪上下文时，对应运行时日志可包含 trace_id、span_id 和 trace_flags。没有活动追踪上下文的日志不包含这些字段，因此后台生命周期事件等日志可能没有追踪 ID。

传递追踪上下文

支持追踪的 MCP 客户端可在请求元数据中提供 W3C 上下文：

json

{
  "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 中查看受管理服务器的后端日志，或查看远程后端自己的日志。运行时事件只记录有限的错误信息。

日志与追踪上下文 ​

选择日志输出位置 ​

阅读运行时日志 ​

传递追踪上下文 ​

隐私与后端诊断 ​

常见问题 ​