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. 创建账号、组织和项目

在浏览器中打开 http://localhost:5173。
使用你的邮箱和密码创建账号。
创建一个 Organization（组织） 用于管理项目。
在组织下创建一个 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/路线图功能。当前所有请求都被视为匿名，默认不会将用户身份与追踪数据关联。项目计划在未来版本中加入用户追踪和用户级别分析支持。