tracehub-mcp

tracehub-mcp

也列于官方 MCP 注册表，名称为 io.github.mcpsmiths/tracehub-mcp（注册表自身的 ?search= 端点可能会优先显示过时版本；此精确名称端点始终反映当前 isLatest 版本），也列于 mcprush。

让 AI 助手直接连接到你的可观测性后端。 tracehub-mcp 是一个 MCP（Model Context Protocol）服务，可让 Claude、Cursor、Windsurf、Gemini CLI 或任何 MCP 客户端查询 LLM/GenAI 应用的 OpenTelemetry 追踪数据并进行分析——找出高开销调用、调试错误、比较模型性能、跟踪令牌用量，而无需将追踪 JSON 复制粘贴到聊天窗口。

它原生支持 OpenTelemetry 的 gen_ai.* 语义约定，因此能将提示词、补全内容、令牌用量和结束原因作为一等概念理解，而不只是通用的 span 属性。

tracehub-mcp 最初是 traceloop/opentelemetry-mcp-server（Apache 2.0）的分支——完整的署名和分支历史见 NOTICE。它已发展为一个支持 8 种后端、经过安全加固的服务，由 mcpsmiths 独立维护；以下的与上游的差异介绍了此处新增的内容。

目录

• 快速开始
• 支持的后端
• 与上游的差异
• 安装
• 配置
• 诊断
• 安全注意事项
• 隐私政策
• MCP 客户端设置
• 工具参考
• 通用筛选系统
• 查询示例
• 常见工作流
• 开发
• 故障排除
• 路线图
• 许可证
• 支持

快速开始

tracehub-mcp 已发布到 PyPI。无需安装——uvx 会一次性获取并运行它：

// claude_desktop_config.json
{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

也可以直接从 Claude Code 使用：

claude mcp add tracehub-mcp -e BACKEND_TYPE=jaeger -e BACKEND_URL=http://localhost:16686 -- uvx tracehub-mcp

就这么简单。 向助手提问：“显示过去一小时内出现错误的追踪记录。”

Cursor、Windsurf、VS Code 和 Gemini CLI 的设置方法见 MCP 客户端设置；pip/pipx/从源码安装等替代方式见安装。

支持的后端

• Jaeger — 本地部署或可自托管，是最常见的开源追踪后端。无需身份验证（可通过 BACKEND_API_KEY 发送 Bearer 令牌；拒绝 BACKEND_URL 中嵌入的凭据）。
• Grafana Tempo — 本地部署或 Grafana Cloud，支持原生 TraceQL 搜索。
• Traceloop — 云端大模型可观测性平台，使用 API 密钥进行身份验证。
• Datadog — 云端 APM，需要 API 密钥 和 Application 密钥。
• Sentry — 云端或可自托管，需要身份验证令牌和组织别名。
• AWS X-Ray — 通过 boto3 使用 SigV4 签名，需要 AWS 区域和标准 AWS 凭据（而非 API 密钥）。由于默认情况下，OTel Span 属性会写入未编入索引的 X-Ray Segment metadata（只有 annotations 可供查询），因此这里的原生服务端筛选能力比其他后端更有限 — 参见后端支持矩阵。
• New Relic — NerdGraph GraphQL API，需要 User API 密钥（而非 Ingest/License 密钥）和账户 ID。构建时未使用实际账户进行验证 — 具体哪些假设未经验证，请参见下文的 New Relic 设置部分以及 backends/newrelic.py 中的模块文档字符串。
• Honeycomb — Query Data API，需要 Configuration Key 和数据集别名。构建时未使用实际账户进行验证；研究发现，以编程方式调用 Query Data API（实际运行查询并获取结果的唯一方式）据文档说明仅限 Enterprise 套餐使用 — 参见下文的 Honeycomb 设置部分以及 backends/honeycomb.py 中的模块文档字符串。

这八种后端都实现了相同的 BaseBackend 接口，因此无论服务连接到哪种后端，每个 MCP 工具的工作方式都完全一致。各后端的设置方式请参见配置。

与上游的不同之处

上游的 opentelemetry-mcp-server 提供了 Jaeger、Tempo 和 Traceloop。tracehub-mcp 新增了 Datadog 和 Sentry 作为完整后端——不是薄封装，而是实现了每项工具的完整功能（搜索、Span 搜索、Trace 补全、服务发现、健康检查）。与此同时，所有五个后端——包括从上游继承的三个——都经过加固，达到一致的标准：

• 云后端仅允许 HTTPS。 Datadog 和 Sentry 都拒绝使用纯 http:// URL 启动，因为它们的认证方式是 Bearer Token 或 API+App 密钥对，不应通过明文传输。
• 安全转义，防止查询注入。 所有拼接到 Datadog Span 搜索查询或 Sentry Discover 查询中的值，都会经过转义并用精确匹配的引号括起；字段名称（因为它们来自 MCP 工具的 filters 参数，不那么明显地属于不可信输入）在拼接到查询字符串之前，会根据允许的模式进行验证，从而杜绝通过精心构造的字段名称进行结构性注入。
• 所有使用游标分页的后端都限制分页范围（Datadog、Sentry）——搜索会在达到请求的 limit 或后端不再返回后续游标时停止，以先发生者为准，因此单次工具调用不会退化成无界抓取。
• 重新验证精确 ID。 当后端搜索 API 可能返回相邻结果而非精确匹配时（尤其是 Datadog 从分组 Span 重建 Trace 的情况），返回前都会将每个结果与请求的精确 ID 重新核对。
• 对于我们构建的后端，畸形响应不会生成虚构数据。 Datadog 和 Sentry 会直接拒绝 Span，而不是在缺少时间戳时用 now() 这类占位值替代，或在缺少 service_name/operation_name 时填入字面值 "unknown"，因为虚构值会悄然破坏 Trace 排序、时长汇总，以及任何按服务或操作分组的工具。（从上游继承的三个后端——Jaeger、Tempo、Traceloop——早于这项规范，尚未进行改造；这是有意控制范围，而非疏忽，体现了本项目一贯的做法：未经完整回归测试，不触及共享或继承的代码。）

这一切都有 458 项测试通过（2 项跳过，零回归）、干净通过的 ruff check 和 mypy --strict，以及针对新后端的两轮对抗式 CodeRabbit 审查作为保障。

安装

tracehub-mcp 已发布到 PyPI。选择你当前工作流中使用的方式即可——它们效果相同。

选项 1：uvx（无需安装）

uvx tracehub-mcp --backend jaeger --url http://localhost:16686

上方的快速入门配置使用的就是这种方式——uv 会一次性获取软件包并运行 tracehub-mcp 入口点，各次运行之间不会在磁盘上留下任何内容。

选项 2：pip / pipx

pipx install tracehub-mcp
# or: pip install tracehub-mcp

tracehub-mcp --backend jaeger --url http://localhost:16686

选项 3：克隆并从源代码运行

git clone https://github.com/mcpsmiths/tracehub-mcp.git
cd tracehub-mcp
uv sync

uv run tracehub-mcp --backend jaeger --url http://localhost:16686

如果你要在本地开发、希望固定到特定提交，或希望安装开发工具（uv sync --group dev），请使用此方式。

选项 4：Docker

# The image's CMD binds 0.0.0.0 inside the container, so a caller token is
# mandatory: clients send it as `Authorization: Bearer $MCP_HTTP_BEARER_TOKEN`.
export MCP_HTTP_BEARER_TOKEN=$(openssl rand -hex 32)
docker run --rm -p 8000:8000 \
  -e BACKEND_TYPE=jaeger -e BACKEND_URL=http://host.docker.internal:16686 \
  -e MCP_HTTP_BEARER_TOKEN \
  -e MCP_ALLOWED_HOSTS=localhost \
  ghcr.io/mcpsmiths/tracehub-mcp:latest

在缓冲后端响应之前，会将其限制为 BACKEND_MAX_RESPONSE_BYTES（默认解码后为 64 MiB），但服务许多会话的容器仍可受益于 Docker 自带的防护措施：添加 --memory 1g --restart unless-stopped（或对应的 Compose 配置），这样即使进程耗尽内存，也会受到限制并自动恢复运行，无需运维人员介入。

默认运行 HTTP 传输（镜像的 CMD），并且必须设置 MCP_HTTP_BEARER_TOKEN 才能启动；也可以显式设置 -e MCP_ALLOW_UNAUTHENTICATED_HTTP=true 选择不进行身份验证，但这样一来，所有能够访问已发布端口的对端都能获得后端的完整读取权限。客户端通过 Authorization: Bearer <token> 连接到 http://localhost:8000/mcp；/health 和 /ready（镜像的 HEALTHCHECK）无需令牌。由于 CMD 绑定到 0.0.0.0，只有设置 MCP_ALLOWED_HOSTS 时，容器才会验证 Host 标头；务必将其设为客户端使用的主机名（上例中为 localhost，实际部署中则为公共名称）；* 会关闭 Host 验证，且不能与其他名称混用（否则服务器将拒绝启动）。对于配置中使用 command/args 键值对直接指向 docker，而非本地二进制文件的 MCP 客户端（Cursor、Windsurf），也应使用这种配置形式——在 args 中传入相同的 -e MCP_HTTP_BEARER_TOKEN=...。

**前提条件：**Python 3.11+；选项 1 和 3 还需要 uv；选项 4 需要 Docker。

配置

配置可以通过环境变量、CLI 标志或两者共同提供。优先级：CLI 参数 > 环境变量 > 默认值。

# .env (see .env.example)
BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686

# Equivalent via CLI flags
tracehub-mcp --backend jaeger --url http://localhost:16686

所有配置选项

**已知的第三方出站网络依赖：**底层 FastMCP 框架每 12 小时会在打印启动横幅时检查 PyPI（https://pypi.org/pypi/fastmcp/json），查看是否有更新版本的 FastMCP——这是 FastMCP 自身的行为，与 tracehub-mcp 无关，也不同于上文所述的 OTel 自监测。无法访问网络时，此检查会静默失败。对于网络受限或隔离网络部署，可设置 FASTMCP_CHECK_FOR_UPDATES=off 禁用此检查；也可设置 FASTMCP_SHOW_SERVER_BANNER=false 完全隐藏横幅。

按后端配置

BACKEND_TYPE=jaeger
BACKEND_URL=http://localhost:16686

BACKEND_TYPE=tempo
BACKEND_URL=http://localhost:3200

BACKEND_TYPE=tempo
BACKEND_URL=https://tempo-prod-XX-prod-XX-XXXX.grafana.net
BACKEND_TEMPO_INSTANCE_ID=your_stack_instance_id
BACKEND_API_KEY=your_cloud_access_policy_token

BACKEND_TYPE=traceloop
BACKEND_URL=https://api.traceloop.com
BACKEND_API_KEY=your_api_key_here

BACKEND_TYPE=datadog
# US site (default): https://api.datadoghq.com
# EU site:            https://api.datadoghq.eu
BACKEND_URL=https://api.datadoghq.com
BACKEND_API_KEY=your_api_key_here
BACKEND_APP_KEY=your_application_key_here

BACKEND_TYPE=sentry
# SaaS (may be region-specific, e.g. https://us.sentry.io):
BACKEND_URL=https://sentry.io
BACKEND_API_KEY=your_auth_token_here
BACKEND_SENTRY_ORG=your-org-slug
# Optional: narrow queries to one project
BACKEND_SENTRY_PROJECT=your-project-slug

BACKEND_TYPE=xray
# Decorative only - never dereferenced for a live request. Keep it
# consistent with BACKEND_AWS_REGION by convention.
BACKEND_URL=https://xray.us-east-1.amazonaws.com
BACKEND_AWS_REGION=us-east-1

BACKEND_TYPE=newrelic
# US datacenter (default): https://api.newrelic.com/graphql
# EU datacenter:            https://api.eu.newrelic.com/graphql
BACKEND_URL=https://api.newrelic.com/graphql
BACKEND_API_KEY=your_user_api_key_here
BACKEND_NEWRELIC_ACCOUNT_ID=1234567

BACKEND_TYPE=honeycomb
# US instance (default): https://api.honeycomb.io
# EU instance:            https://api.eu1.honeycomb.io
BACKEND_URL=https://api.honeycomb.io
BACKEND_API_KEY=your_configuration_key_here
BACKEND_HONEYCOMB_DATASET=your-dataset-slug

Go/no-go 风险，不只是未经验证的细节。 此后端的研究发现，程序化 Query Data API（create-query-result + get-query-result）是实际运行查询并获取数据的唯一方式，且文档显示它仅适用于 Enterprise 计划；Free 和 Pro 账户可以通过 API 构建查询规范，但无法执行查询。如果返回 402/403，此后端会抛出明确的 HoneycombEnterpriseRequiredError，但我们从未通过实际测试确认非 Enterprise 账户会返回的具体状态码，而且此后端的开发完全没有使用实际账户（无论是否为 Enterprise 账户）。在生产环境依赖此后端之前，请参阅 backends/honeycomb.py 中的模块文档字符串，了解完整的未经验证假设列表——包括如何从以聚合为导向的 Honeycomb Query API 中提取原始的每条 Span 数据。

传输模式

# stdio (default) — local use, Claude Desktop, single process
uvx tracehub-mcp
tracehub-mcp                      # pipx/pip install
uv run tracehub-mcp               # from-source install

# HTTP — remote access, multiple clients, network deployment, sample applications
# Loopback (the default --host) needs no token: same-machine clients use http://127.0.0.1:8000/mcp
uvx tracehub-mcp --transport http --port 8000
# Every interface: a caller token is mandatory (or the explicit --allow-unauthenticated-http opt-out)
export MCP_HTTP_BEARER_TOKEN=$(openssl rand -hex 32)
uvx tracehub-mcp --transport http --host 0.0.0.0 --port 8000
tracehub-mcp --transport http --host 0.0.0.0 --port 8000              # pipx/pip install
uv run tracehub-mcp --transport http --host 0.0.0.0 --port 8000       # from-source install

使用 HTTP 传输时，客户端会连接到 http://<host>:<port>/mcp（可流式 HTTP，兼容各类 MCP 客户端）；每当设置了 MCP_HTTP_BEARER_TOKEN，客户端都必须在每个请求中发送 Authorization: Bearer <token>——缺少令牌或令牌错误时会返回带有 WWW-Authenticate: Bearer 挑战的 401，且不会打开会话。uvicorn 的逐请求访问日志默认关闭（通过 --access-log / MCP_ACCESS_LOG=true 可重新启用；启用后会从每一行日志中剥离查询字符串、片段、矩阵参数（;，uvicorn 会将其记录为 %3B）和百分号编码的 ?/#，并将日志路径截断至 2 KiB；但放在路径段中的令牌仍会被记录）：否则它会将完整请求目标写入服务器日志——包括配置错误的客户端放在查询字符串中的令牌——而日志中没有任何内容是必要的；请求级诊断信息来自服务器自身受限的 Host/Origin 拒绝日志和速率限制日志、慢请求 WARNING，以及启用时的 OTel Span。

绑定到回环地址时，也会自动验证 Host 标头（回环名称和绑定地址会通过，其他值会返回 421），从而防止 DNS 重绑定攻击：浏览器页面发出的、没有 Origin 的 GET 请求携带攻击者提供的 Host。如果同主机反向代理转发到 127.0.0.1 并保留了公网 Host（nginx 默认的 proxy_set_header Host $proxy_host 不会这样做），请在 --allowed-hosts/MCP_ALLOWED_HOSTS 中列出该名称。网络绑定也能获得同样的保护，前提是在 --allowed-hosts 中列出公网主机名；--allowed-hosts '*' 可关闭保护，且必须单独使用（启动时会拒绝将 * 与其他名称混用的列表）。

Fly.io： 一键命令 fly mcp launch 仅支持 stdio 传输服务器—— 无法部署此服务器的 --transport http 模式。在 Fly.io 上使用 HTTP 传输运行 tracehub-mcp， 需要改用手动配置 fly.toml 并执行 fly deploy。

诊断

将配置接入实际的 MCP 客户端前，请先验证：

tracehub-mcp doctor --backend jaeger --url http://localhost:16686

[OK] Configuration loaded and validated
[OK] Backend constructed: jaeger @ http://localhost:16686/
[OK] Health check: healthy
[OK] Connectivity probe (list_services): 2 service(s)

doctor 接受与主命令相同的 --backend/--url/等标志；如果任何步骤失败，它都会以非零状态码退出。与此不同，常规服务启动会延迟初始化后端，即使初始健康检查失败，也会有意继续运行。

如需查看完全解析后的配置（合并了环境变量和 CLI 覆盖项），但不启动服务：

tracehub-mcp --print-config --backend jaeger --url http://localhost:16686

密钥（--api-key/--app-key）会以 api_key_set/app_key_set 布尔值报告，不会显示实际值。

安全注意事项

此服务返回的跟踪和跨度数据——属性值、错误消息、操作名称——来自可观测性后端正在监控的应用，而非 tracehub-mcp 本身。因此，尽管是受信任的服务（本服务）将这些数据返回给 MCP 客户端，但从根本上说，这些数据与网页或文件一样，都属于不受信任的外部内容。

• HTTP 传输会以你的后端凭据运行每个工具，因此请对调用方进行身份验证。 --transport http 默认绑定到环回地址（127.0.0.1）。若要在网络接口上提供服务（--host 0.0.0.0，Docker 镜像的 CMD），则必须设置 MCP_HTTP_BEARER_TOKEN（客户端发送 Authorization: Bearer <token>）；除非传入 --allow-unauthenticated-http，以接受任何能够访问该端口的对端都能获得后端的完整读取权限，否则服务会拒绝启动。你也可以保持绑定到环回地址，并在专用网络上使用需要身份验证的反向代理。/health 和 /ready 始终无需令牌。
• 后端凭据绝不能放在 BACKEND_URL 中。 含有 user:password@host 的 URL 会在启动时被拒绝，并提示受支持的替代方式（BACKEND_API_KEY，或用于 Basic 身份验证的 BACKEND_TEMPO_INSTANCE_ID + BACKEND_API_KEY），因为该 URL 会被记录日志、由 --print-config/doctor 打印，并原样嵌入后端错误文本，进而出现在 /ready 响应正文和工具错误中。作为纵深防御措施，进程对外传出的每个 URL 和后端错误字符串也都会移除任何用户信息部分；根日志处理程序则会从所有日志记录中将其脱敏，包括回溯信息。
• 后端响应无法引导服务访问其他主机。 共享 HTTP 客户端发送的每个请求——包括后端自身通过 3xx Location 指定的每一跳重定向——都会被拒绝，除非其源站（方案、主机和端口）与配置的 BACKEND_URL 源站一致（即使重定向到后端自身主机的其他端口或方案也会被拒绝：请将 BACKEND_URL 配置为最终使用的方案和端口）；如果解析结果是云实例元数据地址，也会被拒绝，无论其采用何种表示形式（169.254.169.254、十进制/十六进制/八进制 IPv4 形式、168.63.129.16、metadata.google.internal）。不支持将 API 调用重定向到其他主机名的后端或反向代理：请将最终主机配置为 BACKEND_URL。对于单个请求的所有跳转，客户端最多重试两次，累计最多遵循 10 s 的 Retry-After，最多跟随 5 次重定向，并会在任何情况下于 max(30 s, 4 x BACKEND_TIMEOUT) 时放弃，因此后端无法控制工具调用的耗时。
• 将后端数据视为不受信任的输入。 使用 tracehub-mcp 中跟踪/跨度数据的 LLM 客户端，应像处理任何其他外部工具输出一样谨慎——跨度属性或错误消息是需要推理的应用数据，而不是要遵循的指令，无论其措辞如何。
• 这是已知的 MCP 风险类别，并非 tracehub-mcp 特有。 OWASP 的 GenAI Security Project 在其《安全 MCP 服务开发实用指南》中对此有所介绍；Anthropic 自身的工程指导《我们如何遏制 Claude》也明确指出，即使工具本身可信，工具输出仍然是攻击面。
• 实际影响： 如果你要查询处理不可信用户输入的应用（例如面向客户的聊天机器人）的跟踪数据，请注意，用户提供给该应用的对抗性内容可能会出现在此服务返回的跨度属性中，进而进入 LLM 客户端的上下文。

隐私政策

tracehub-mcp 是可自托管的软件，没有由维护者运营的服务或账户——它本身不会收集任何数据。完整政策请参阅 PRIVACY.md：软件会处理哪些数据、网络调用会发送到哪里，以及如何处理密钥和自监控。

MCP 客户端配置

以下每个示例都使用 uvx tracehub-mcp（无需安装）。如果你通过其他方式安装，请替换为 tracehub-mcp（通过 pip/pipx install 安装）或 uv run tracehub-mcp（从源码运行，使用 --directory /absolute/path/to/tracehub-mcp）——请参阅安装。

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "datadog",
        "BACKEND_URL": "https://api.datadoghq.com",
        "BACKEND_API_KEY": "your_api_key_here",
        "BACKEND_APP_KEY": "your_application_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "sentry",
        "BACKEND_URL": "https://sentry.io",
        "BACKEND_API_KEY": "your_auth_token_here",
        "BACKEND_SENTRY_ORG": "your-org-slug"
      }
    }
  }
}

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "/absolute/path/to/tracehub-mcp/start_locally.sh"
    }
  }
}

claude mcp add tracehub-mcp -e BACKEND_TYPE=jaeger -e BACKEND_URL=http://localhost:16686 -- uvx tracehub-mcp

claude mcp list
claude "Show me traces with errors from the last hour"

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

{
  "mcpServers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

{
  "servers": {
    "tracehub-mcp": {
      "command": "uvx",
      "args": ["tracehub-mcp"],
      "env": {
        "BACKEND_TYPE": "jaeger",
        "BACKEND_URL": "http://localhost:16686"
      }
    }
  }
}

gemini "Analyze token usage for gpt-4 requests today"

工具参考

tracehub-mcp 提供 19 个 MCP 工具：

后端支持矩阵

_{* Jaeger 的跨度搜索需要 service_name 参数。
† Datadog、AWS X-Ray、New Relic 和 Honeycomb 没有跟踪级别的搜索 API（X-Ray 的 BatchGetTraces 按精确 ID 获取）；它们通过搜索（跨度、X-Ray 跟踪摘要、NRQL Span 事件或 Honeycomb 分解组）并补全数据来重建跟踪，且每个结果都会再次与请求的精确 ID 核对。
‡ Sentry 和 New Relic 都有原生跟踪查询端点（Datadog 和 Honeycomb 则没有），因此 get_trace 会直接调用该端点；search_traces 仍会先通过跨度/NRQL 搜索来发现候选跟踪 ID，因为这两个后端的搜索界面本身都以跨度为中心。
§ AWS X-Ray 原生仅支持按服务名称、持续时间以及根据错误/故障/限流推导出的状态进行筛选——OTel 属性（包括所有 gen_ai.* 字段）默认会存入未编制索引的段元数据，而不是已编制索引的注释，因此始终由客户端处理，而不会下推到 FilterExpression。
¶ New Relic：search_spans 直接从 NRQL 文档详述的扁平行结构中读取 gen_ai.* 属性；search_traces/get_trace 还依赖一个未经验证的假设，即 NerdGraph 的 distributedTracing.trace 响应中 attributes 字段的结构符合预期。通过将原始搜索行的属性覆盖回补全后的结果来缓解此问题。Honeycomb：gen_ai.* 属性通过与其他所有字段相同的分解列技术提取（模块文档字符串第 2 点），这种提取方法同样未经验证。
♦ 上方 Honeycomb“搜索”/“按 ID 获取跟踪”整行勾选均依赖 Query Data API；该后端的相关研究发现，文档说明此 API 仅限 Enterprise 套餐使用——Free/Pro 账户可能无法使用这些功能。请参阅上方 Honeycomb 设置部分。}

主要工具详情

search_traces

{
    "service_name": "my-app",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-01T23:59:59Z",
    "gen_ai_system": "openai",
    "gen_ai_request_model": "gpt-4",
    "min_duration_ms": 1000,
    "has_error": false,
    "limit": 50,
}

参数：service_name、operation_name、start_time/end_time（ISO 8601）、min_duration_ms/max_duration_ms、gen_ai_system、gen_ai_request_model、gen_ai_response_model、has_error、tags、filters（参见通用筛选系统）、limit（1–1000，默认值为 100）。返回包含 token 数量的跟踪摘要。

get_trace

{"trace_id": "abc123def456"}

返回完整的跟踪树：所有包含属性的跨度、为 LLM 跨度解析出的 OpenTelemetry gen_ai.* 数据、每个跨度的 token 使用量、错误信息，以及每个跨度的原始 events（例如 gen_ai.evaluation.result，或其他任何由检测工具发出的事件——不会限制为固定的一组名称）。

triage_trace

{"trace_id": "abc123def456", "detail_level": "summary"}

与其每次都返回原始跟踪数据，让 Agent 重新推导诊断结果，不如直接综合生成诊断：关键路径（即实际决定跟踪总延迟的“最后完成的子项”链）、按自身耗时排序的主要 span（扣除子项耗时后的延迟贡献），以及——当跟踪中包含错误时——错误链中最深层的错误 span，作为可能的根因（confidence: "high"；若存在多个深度相同的错误链，导致责任归属不明确，则为 "medium"）。若不存在错误，则回退为以自身耗时最高的 span 作为纯延迟诊断（confidence: "low"）。结果具有确定性——不会调用 LLM——且适用于任何已配置的后端，因为它使用的是 get_trace 已获取的 span 数据。detail_level: "full" 还会在诊断结果由错误驱动时附上已判定根因的原始错误详情（消息／类型／堆栈跟踪）。无论跟踪深度如何，结果都有长度上限：在摘要模式下，error_chain 和 critical_path 各最多列出 25 个 span——开头 5 个和结尾 20 个 span，中间以一条明确的 [K intermediate span(s) elided] 条目省略，并在推理中注明实际深度；detail_level: "full" 则将上限提高到 1000 个。如果跟踪没有根 span（存在父级循环），则会如实报告这一情况，并将 confidence 设为 "low"，而不是将其报告为深度问题。

correlate_trace

{"trace_id": "abc123def456"}

尝试在第二个独立配置的后端中查找对应的跟踪（例如，将 Datadog 跟踪与其下游 Sentry 错误关联起来）。首先尝试在次要后端中直接匹配 trace_id（confidence: "high"）；若失败，则回退到结合时间窗口和服务名称重合度的启发式搜索（confidence: "low"）。它会按主跟踪中的每个服务名称各查询一次，因此也适用于 Jaeger 这类要求 search_traces 提供 service_name 的后端。最多搜索 span 数量最多的 10 个服务，避免单个跟踪触发数百次次要后端查询。每个匹配结果还会报告 root_cause_consistent：如果两个跟踪都没有错误可供比较，则为 null；否则为 true／false，表示两端是否对错误及其所属服务达成一致（复用 triage_trace 使用的同一错误链逻辑）。这是尽力而为的关联，并非保证成功的连接——结果始终包含固定的 limitations（时钟偏差、采样不匹配、跟踪可见性不完整，以及即使正常采用 W3C Trace Context 传播，跨供应商边界也无法保证 trace ID 连续性），以及每次调用产生的任何截断说明：启发式搜索窗口从主跟踪开始时间起最多为 24 h，无论主跟踪 span 所显示的时间跨度有多长，避免单个跟踪导致服务扫描次要后端中数年的数据；如果跳过了超过 10 个服务的部分，结果也会注明。需要通过 SECONDARY_BACKEND_TYPE／SECONDARY_BACKEND_URL 配置次要后端（参见配置表）；否则会返回明确的错误。

get_llm_usage

{
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-01T23:59:59Z",
    "service_name": "my-app",
    "gen_ai_system": "openai",
    "limit": 1000,
}

返回按模型和服务细分的提示词／补全／总 token 汇总，以及请求数量。

list_services — 无参数。返回已插桩的服务名称列表。

find_errors

{"start_time": "2024-01-15T14:00:00Z", "service_name": "my-app", "limit": 50}

返回错误消息、错误类型、截断后的堆栈跟踪，以及 LLM 专属错误信息。

list_llm_models / get_llm_model_stats / get_llm_expensive_traces / get_llm_slow_traces / list_llm_tools_tool / search_spans_tool / list_sessions / get_session_stats / compare_time_windows / investigate_cost_spike / investigate_error_spike / get_prompt_version_stats 均在 CLAUDE.md 中附有详细说明和完整示例——本 README 介绍所有工具通用的结构；有关 LLM 分析工具的确切参数和响应字段，请参阅更全面的参考文档 CLAUDE.md。

通用过滤系统

search_traces 和 search_spans_tool 除了（或替代）简单的命名参数外，还都接受 filters 列表，用于执行高级查询。每个过滤器如下：

{
  "field": "gen_ai.usage.total_tokens",
  "operator": "gt",
  "value": 5000,
  "value_type": "number"
}

• field — 点分隔的属性名称，例如 gen_ai.usage.prompt_tokens、traceloop.span.kind、service.name（1–256 个字符）
• operator — 见下表
• value — 单个值（适用于大多数运算符），或 values — 列表（适用于 in、not_in、between；最多 100 个值）
• value_type — "string"、"number" 或 "boolean"

限制与验证。 单次调用最多接受 50 个 filters 和 50 个 tags（两项限制独立计算，不共用额度），每个 in/not_in 过滤器最多接受 100 个 values，且 field 名称长度为 1–256 个字符，因此单个查询生成的后端子句数量始终有上限。操作数会在发送任何内容之前按声明的 value_type 进行规范化："number" 下的 "5000" 等数字字符串会被接受并强制转换，而非数字字符串（"abc"）、非有限值或大到无法用双精度数表示的整数会被拒绝；"boolean" 接受 JSON 布尔值或字符串 "true"/"false"；"string" 接受数字或布尔值，并将其转换为字符串。包含未知键的过滤器对象会被拒绝，而不会被静默忽略。超出限制或未通过验证时，会在发出任何后端请求之前返回工具错误。

多个过滤器以 AND 逻辑组合。旧版简单参数（service_name、gen_ai_request_model 等）仍然有效，并会在内部转换为过滤器 — 可自由混用。

服务端采用 混合过滤策略：在后端支持的情况下，将过滤器转换为后端原生查询语言（Tempo 的 TraceQL、Datadog 的 span 搜索语法、Sentry 的 Discover 语法）；对于后端无法原生表达的过滤条件，则在客户端应用。

示例 — 耗时较长的 OpenAI 轨迹：

{
  "filters": [
    { "field": "gen_ai.system", "operator": "equals", "value": "openai", "value_type": "string" },
    { "field": "gen_ai.usage.total_tokens", "operator": "gt", "value": 5000, "value_type": "number" }
  ]
}

完整的语义约定属性列表（gen_ai.* 与旧版 llm.* 的区别、不同提供方的令牌命名变体、完成原因取值以及令牌计算回退链），请参阅 CLAUDE.md。

查询示例

查找耗时较长的 OpenAI 操作

提问： “显示过去一小时内耗时超过 5 秒的 OpenAI 轨迹”

工具调用： search_traces

{
  "service_name": "my-app",
  "gen_ai_system": "openai",
  "min_duration_ms": 5000,
  "start_time": "2024-01-15T10:00:00Z",
  "limit": 20
}

响应：

{
  "traces": [
    {
      "trace_id": "abc123...",
      "service_name": "my-app",
      "operation_name": "chat.completions",
      "status": "OK",
      "duration_ms": 8250,
      "span_count": 3,
      "llm_span_count": 1,
      "total_tokens": 4523,
      "has_errors": false
    }
  ],
  "count": 1
}

按模型分析 Token 用量

提问： “今天每个模型用了多少 Token？”

工具调用： get_llm_usage

{
  "start_time": "2024-01-15T00:00:00Z",
  "end_time": "2024-01-15T23:59:59Z",
  "service_name": "my-app"
}

响应：

{
  "period": { "start_time": "2024-01-15T00:00:00Z", "end_time": "2024-01-15T23:59:59Z" },
  "filters": { "service_name": "my-app" },
  "summary": {
    "total_requests": 487,
    "total_prompt_tokens": 82140,
    "total_completion_tokens": 43290,
    "total_tokens": 125430
  },
  "by_model": {
    "gpt-4": { "requests": 156, "prompt_tokens": 58300, "completion_tokens": 26900, "total_tokens": 85200 },
    "gpt-3.5-turbo": { "requests": 331, "prompt_tokens": 23840, "completion_tokens": 16390, "total_tokens": 40230 }
  },
  "by_service": {
    "my-app": { "requests": 487, "prompt_tokens": 82140, "completion_tokens": 43290, "total_tokens": 125430 }
  }
}

查找有错误的跟踪记录

提问： “显示过去一小时内的所有错误”

工具调用： find_errors

{
  "start_time": "2024-01-15T14:00:00Z",
  "service_name": "my-app",
  "limit": 10
}

响应：

{
  "count": 1,
  "error_traces": [
    {
      "trace_id": "def456...",
      "service_name": "my-app",
      "operation_name": "chat.completions",
      "start_time": "2024-01-15T14:23:15Z",
      "duration_ms": 1200,
      "status": "ERROR",
      "span_count": 2,
      "llm_span_count": 1,
      "total_tokens": 310,
      "has_errors": true,
      "error_spans": [
        {
          "span_id": "span789...",
          "operation_name": "chat.completions",
          "service_name": "my-app",
          "status": "ERROR",
          "error_message": "RateLimitError: Too many requests",
          "error_type": "openai.error.RateLimitError",
          "is_llm_error": true,
          "llm_provider": "openai",
          "llm_model": "gpt-4"
        }
      ]
    }
  ]
}

比较模型性能

提问： “GPT-4 和 Claude 的性能差异是什么？”

工具调用 1： 对 gpt-4 调用 get_llm_model_stats

{ "model_name": "gpt-4", "start_time": "2024-01-15T00:00:00Z" }

工具调用 2： 对 claude-3-opus 调用 get_llm_model_stats

{ "model_name": "claude-3-opus-20240229", "start_time": "2024-01-15T00:00:00Z" }

调查 Token 用量过高的问题

提问： “今天哪些请求使用的 Token 最多？”

工具调用： get_llm_expensive_traces

{ "limit": 10, "start_time": "2024-01-15T00:00:00Z", "min_tokens": 5000 }

常见工作流

成本优化

1. get_llm_expensive_traces — 找出 Token 用量最高的请求
2. get_llm_usage — 查看哪些模型的成本最高
3. 对特定的 trace_id 调用 get_trace — 检查确切的提示词/响应

性能调试

1. get_llm_slow_traces — 找出延迟异常值
2. find_errors — 检查失败模式
3. get_llm_model_stats — 检查结束原因分布，排查截断问题

模型采用情况跟踪

1. list_llm_models — 查看实际调用的所有模型
2. 按模型调用 get_llm_model_stats — 比较性能
3. 扫描 list_llm_models 的结果，查找意外出现的模型/服务（影子 AI）

开发

git clone https://github.com/mcpsmiths/tracehub-mcp.git
cd tracehub-mcp
uv sync --group dev   # pulls in pytest, mypy, ruff, etc. for local iteration

# Tests (458 passed, 2 skipped at time of writing)
uv run pytest

# With coverage
uv run pytest --cov=opentelemetry_mcp --cov-report=html

# Format, lint, type-check
uv run ruff format .
uv run ruff check .
uv run mypy src/

CI（.github/workflows/ci.yml）会在每次推送时运行 Ruff 和 mypy（严格模式），以及完整的 pytest 测试套件。

mcpb pack mcpb/ 会构建 Claude Desktop 安装包。mcpb/.mcpbignore 是一个拒绝列表（mcpb 不会读取 .gitignore）：mcpb/ 下所有未被它或 mcpb 内置模式列出的文件，无论是否已跟踪，都会被打包——请从干净的工作树中打包（git status --short mcpb/ 不应有任何输出），并在发布安装包前检查打印出的文件数。

故障排除

后端连接问题：

curl http://localhost:16686/api/services   # Jaeger
curl http://localhost:3200/api/search/tags  # Tempo

身份验证错误： 确认已设置密钥 —

export BACKEND_API_KEY=your_key_here
# or: tracehub-mcp --api-key your_key_here

未找到跟踪记录：

• 检查时间范围（使用最近的时间戳）
• 使用 list_services 验证服务名称
• 先尝试不带筛选条件进行搜索

Token 用量显示为零：

• 确认跟踪记录包含 OpenTelemetry gen_ai.*（或旧版 llm.*）检测信息
• 使用 get_trace 检查原始跨度属性

Datadog/Sentry 特定问题： 请参阅配置中各后端下的故障排除说明。

路线图

此前在此列为暂缓的两个想法现已上线：

• 面向 Agent 的故障分诊——标记可能的根本原因，而不只是返回原始追踪数据的工具：请参阅上方工具参考中的 triage_trace。
• 跨后端关联——查询第二个独立配置的后端，并将结果与其关联：请参阅上方的 correlate_trace。根据相关研究，这项功能以尽力而为的启发式关联方式上线（直接匹配 trace_id，或在无法匹配时回退到时间窗口／服务重叠），而非保证能够在架构层面进行联接——即使在正常的 W3C Trace Context 传播下，跨供应商边界的 trace-id 连续性也无法保证。

此后，New Relic 和 Honeycomb 已分别作为第 7 和第 8 个后端上线。两者的实现都完全基于研究和文档，未通过实际账号验证——在生产环境中依赖任一后端之前，请查看各自的设置章节，了解哪些内容尚未验证；其中 Honeycomb 尤其存在实际的 go/no-go 风险（其文档说明，程序化 Query Data API 仅供 Enterprise 计划使用）。目前没有其他正在研究的后端。（Grafana Cloud 从未在此列表中——它目前已通过 Tempo 的 Basic Auth 路径上线；请参阅上方的 Grafana Tempo。）

从上游较早的路线图继承而来、但重新排在上述事项之后，并非已取消的工作包括：专用的模型对比工具（目前的 get_llm_model_stats 和 compare_time_windows 分别支持按模型统计和时间窗口差异对比，但没有可直接比较两个指定模型差异的单一工具）、跨多个模板而非仅针对单个提示词进行版本间对比的更广泛提示词模式分析（get_prompt_version_stats 已支持后者）、用于常见查询的 MCP 资源，以及 SigNoz/ClickHouse 后端支持。内置定价表的成本计算和查询结果缓存层均已上线，并非待办事项：每个报告用量的工具（例如工具参考中的 investigate_cost_spike）都会返回一对 cost_usd/cost_usd_is_partial，其数据由内置的 litellm 定价表（src/opentelemetry_mcp/pricing/）提供支持；查询结果会通过 QUERY_CACHE_TTL_SECONDS 环境变量进行缓存，并合并正在进行的请求（请参阅上方的配置选项总表）。

本 README 其他部分记录的所有功能均已上线。

贡献

欢迎贡献。在提交 PR 之前，请确认：

1. 所有测试均通过：uv run pytest
2. 代码格式正确：uv run ruff format .
3. 没有 lint 错误：uv run ruff check .
4. 类型检查通过：uv run mypy src/

许可证

Apache License 2.0——请参阅 LICENSE。本项目是 traceloop/opentelemetry-mcp-server 的分支；完整的致谢信息和分支关系记录在 NOTICE 中。

支持

• 问题与功能请求： github.com/mcpsmiths/tracehub-mcp/issues
• 更新日志： CHANGELOG.md
• 社区： Traceloop Community Slack（上游社区频道；欢迎提出 OpenTelemetry/GenAI 追踪相关的一般问题）
• 相关资源： Model Context Protocol · OpenTelemetry GenAI 语义约定 · traceloop/opentelemetry-mcp-server（上游）