Heimdall

什么是 Heimdall？

Heimdall 是一个专为 Model Context Protocol（MCP）服务器 和 AI/LLM 应用 设计的开源可观测性平台。它为开发者、平台团队和 AI 工程师提供对 AI 基础设施内部工具、资源和提示词执行情况的深度可见性。

基于 OpenTelemetry 标准，Heimdall 从你的 MCP 工具和 AI 服务中采集并可视化实时链路追踪、指标与分析数据。它被设计为自托管方案，让你完全掌控数据，同时对延迟、错误率、使用模式以及工具行为进行精细监控。

通过在 Python 或 JavaScript/TypeScript MCP 服务器中集成轻量级 SDK，Heimdall 能以最小的代码改动实现对每一次工具调用和资源请求的追踪。对于构建 AI Agent、工具链以及 LLM 驱动后端、并希望获得生产级可观测性且避免厂商锁定的团队而言，这是一个理想选择。

主要特性

• MCP 服务器的实时链路追踪
  实时追踪每一次工具调用、资源访问以及与提示词相关的执行。Heimdall 会展示详细的追踪信息，包括工具何时被调用、耗时多久、传入了哪些参数以及最终是成功还是失败。

• 仪表盘分析与可视化
  使用内置前端仪表盘，分析 AI 服务的延迟、错误率和使用模式。能够快速发现运行缓慢的工具、故障端点或异常的流量峰值。

• 原生支持 OpenTelemetry 的架构
  Heimdall 使用 OTLP/HTTP 作为数据接收协议，并与 OpenTelemetry 标准确保完全对齐。这使其更容易与现有可观测性平台集成，或扩展你的遥测管道。

• 便捷集成的 Python 与 JavaScript/TypeScript SDK
  Heimdall 提供官方 Python SDK（hmdl） 和 JavaScript/TypeScript SDK（hmdl），并配有简单易用的装饰器/包装器：

  • Python：使用 @trace_mcp_tool() 装饰器为 MCP 工具添加追踪。
  • JS/TS：使用 traceMCPTool() 包装异步工具函数。

• 自动参数捕获
  Python SDK 会自动检查函数签名，将参数以命名对象形式捕获（例如 { "query": "test", "limit": 5 }）。JS/TS SDK 则允许通过 paramNames 指定参数名称，从而获得同样的效果，使追踪数据更易阅读，也更便于调试。

• 自托管部署
  目前 Heimdall 仅支持自托管部署，让你完全掌控基础设施、安全与数据驻留位置。你可以在自己的服务器或本地开发环境上运行后端和前端。

• 组织与项目模型
  Heimdall 采用 Organization → Project（组织 → 项目） 结构：

  • 组织用于对相关项目和团队进行分组。
  • 项目代表单个应用或环境，每个项目都有唯一的 Project ID 用于汇聚追踪数据。

• 基于环境的配置方式
  可通过环境变量配置 Heimdall SDK，例如：HEIMDALL_ENDPOINT、HEIMDALL_ORG_ID、HEIMDALL_PROJECT_ID、HEIMDALL_SERVICE_NAME、HEIMDALL_ENVIRONMENT、HEIMDALL_ENABLED，方便在开发、预发布和生产环境中部署。

• 未来路线图（计划中的功能）
  仓库中列出了多项即将推出的能力：

  • 用户追踪：将追踪与用户身份关联，支持用户级别分析（目前所有请求都是匿名）。
  • LLM 评估：内置模型质量评分和人工评审流程。
  • 托管云服务：为不希望自托管的团队提供可选的托管云部署方案。

如何使用 Heimdall

使用 Heimdall 一般分为三步：运行平台、创建组织与项目，以及将 SDK 集成进 MCP 服务器或 AI 应用。

1. 准备前置条件

请确保你具备以下运行时依赖：

• Node.js 18+（用于 Heimdall 后端和前端）
• Python 3.9+（如果计划使用 Python SDK）

从 GitHub 克隆 Heimdall 仓库并进入项目目录。

2. 启动后端

在项目根目录执行：

cd backend
npm install
npm run dev

这将启动 Heimdall 后端，并暴露一个 OTLP/HTTP 端点（默认：http://localhost:4318）用于接收追踪数据。

3. 启动前端

在另一个终端中执行：

cd frontend
npm install
npm run dev

前端通常运行在 http://localhost:5173，提供组织、项目管理和分析的 Web 界面。

4. 创建账号、组织和项目

1. 在浏览器中打开 http://localhost:5173。
2. 使用你的邮箱和密码创建账号。
3. 创建一个 Organization（组织） 用于管理项目。
4. 在组织下创建一个 Project（项目）。每个项目都会获得一个唯一的 Project ID，用于关联接收到的追踪数据。

然后前往项目的 Settings（设置） 页面，找到：

• Organization ID
• Project ID

你将在 SDK 配置中使用这些值。

5. 集成 Python SDK

安装 Python 包：

pip install hmdl

基础集成示例：

from hmdl import HeimdallClient, trace_mcp_tool

# 初始化客户端
client = HeimdallClient(
    endpoint="http://localhost:4318",
    org_id="your-org-id",       # 来自 Settings
    project_id="your-project-id", # 来自 Settings
    service_name="my-mcp-server",
    environment="development"
)

@trace_mcp_tool()
def search_tool(query: str, limit: int = 10) -> dict:
    return {"results": [], "query": query, "limit": limit}

result = search_tool("test", limit=5)
client.flush()

该装饰器会为每次调用 search_tool 自动创建追踪数据，并捕获参数和执行元数据。

6. 集成 JavaScript/TypeScript SDK

安装 JS/TS 包：

npm install hmdl

基础集成示例（TypeScript 风格）：

import { HeimdallClient, traceMCPTool } from 'hmdl';

const client = new HeimdallClient({
  endpoint: "http://localhost:4318",
  orgId: "your-org-id",       // 来自 Settings
  projectId: "your-project-id", // 来自 Settings
  serviceName: "my-mcp-server",
  environment: "development",
});

const searchTool = traceMCPTool(
  async (query: string, limit: number = 10) => ({
    results: [],
    query,
    limit,
  }),
  {
    name: "search-tool",
    paramNames: ["query", "limit"],
  }
);

await searchTool("test", 5);
await client.flush();

7. 通过环境变量进行配置（可选）

你可以使用环境变量配置 Heimdall 客户端，而不必在代码中硬编码：

export HEIMDALL_ENDPOINT="http://localhost:4318"
export HEIMDALL_ORG_ID="your-org-id"
export HEIMDALL_PROJECT_ID="your-project-id"
export HEIMDALL_SERVICE_NAME="my-mcp-server"
export HEIMDALL_ENVIRONMENT="development"
export HEIMDALL_ENABLED="true"

然后即可在不传入参数的情况下初始化客户端：

# Python
from hmdl import HeimdallClient
client = HeimdallClient()

// JavaScript/TypeScript
import { HeimdallClient } from 'hmdl';
const client = new HeimdallClient();

完成集成后，你的 MCP 工具将向 Heimdall 后端发送遥测数据，你可以在 Web 界面中分析追踪与指标。

使用场景

1. AI Agent 与工具链的可观测性

构建复杂 AI Agent 并依赖 MCP 工具的团队，需要了解每个工具在真实负载下的表现。Heimdall 可以提供：

• 按工具粒度的延迟追踪和错误监控。
• 哪些工具被使用得最频繁的可见性。
• 提示词和资源通过这些工具被访问的洞察。

这有助于团队优化工具链、下线使用率低的工具，并更有效地调试 Agent 行为。

2. LLM 驱动后端的生产监控

对于在生产环境运行 LLM 支撑 API 或 AI 微服务 的组织，Heimdall 是关键的可观测性层：

• 监控请求吞吐量与响应时间。
• 精确定位由外部依赖或特定工具导致的慢路径。
• 发现部署后的错误峰值或回归问题。

通过基于 OpenTelemetry 集成 Heimdall，你可以将 AI 可观测性与更广泛的监控栈对齐。

3. MCP 服务器的开发与调试

在开发阶段，Heimdall 帮助工程师 调试新的 MCP 服务器 或工具：

• 在测试期间追踪对新工具的每一次调用。
• 检查参数与返回数据，验证逻辑是否正确。
• 快速查看异常在何处抛出，以及在什么条件下出现。

这加快了反馈循环，减少在多工具、多步骤工作流中定位问题所需的时间。

4. 内部 AI 平台与基础设施团队

为多个产品团队提供 内部 AI 基础设施 的平台团队，可以利用 Heimdall 提供标准化的可观测性能力：

• 为每个应用或租户创建独立项目。
• 监控整个组织范围内的使用情况与性能模式。
• 使用即将提供的用户级追踪（规划中）来理解按团队或客户维度的消耗情况。

这有助于更好地进行容量规划、成本分摊/展示（chargeback/showback）以及提升服务可靠性。

5. 注重隐私或受监管环境

由于 Heimdall 是自托管且开源的，它非常适合在高度监管或安全敏感环境中运行的组织：

• 将所有追踪数据和元数据保留在自己的基础设施中。
• 让部署方式符合内部安全与合规要求。
• 自由定制平台或将其与现有监控和告警工具集成。

常见问题（FAQ）

Heimdall 是否可以免费使用？

可以。Heimdall 以 MIT 许可证 发布，对个人和商业用途均免费且开源。你需要自行在自有基础设施上部署并运行该平台。路线图中也提到未来可能推出托管云服务，但核心项目会保持开源。

Heimdall 使用了哪些技术和标准？

Heimdall 基于 OpenTelemetry 构建，并使用 OTLP/HTTP 协议（默认端口 4318）接收遥测数据。后端和前端均基于 Node.js，官方客户端 SDK 覆盖 Python 和 JavaScript/TypeScript。

支持哪些环境和编程语言？

Heimdall 目前提供以下官方 SDK：

• Python（通过 hmdl 包，需 Python 3.9+）
• JavaScript/TypeScript（通过 hmdl npm 包，需要 Node.js 18+）

由于 Heimdall 使用 OpenTelemetry/OTLP 协议，你也可以通过标准 OpenTelemetry 库在其他语言中集成，不过最佳体验仍来自官方针对 MCP 的 SDK。

我必须自托管 Heimdall 吗？

是的，目前 Heimdall 仅作为自托管平台提供。你需要自行运行后端和前端服务（例如在本地机器、虚拟机、Kubernetes 或其他云服务提供商上）。项目路线图中提到的 托管云服务 仍属于未来规划，尚未在当前版本中提供。

如何为多个环境（开发、预发布、生产）配置 Heimdall？

Heimdall 通过 SDK 参数和环境变量支持按环境配置。常见实践包括：

• 为不同环境使用不同的 Projects（以及视需要使用不同的 Organizations）。
• 在每个环境中分别设置 HEIMDALL_ENDPOINT、HEIMDALL_ORG_ID、HEIMDALL_PROJECT_ID、HEIMDALL_SERVICE_NAME 和 HEIMDALL_ENVIRONMENT 等环境变量。

这样可以在逻辑上隔离不同环境的追踪数据，也便于对比开发、预发布和生产环境的行为。

Heimdall 能否将追踪数据与具体终端用户关联？

用户级追踪目前被标记为 TODO/路线图功能。当前所有请求都被视为匿名，默认不会将用户身份与追踪数据关联。项目计划在未来版本中加入用户追踪和用户级别分析支持。