Heimdall

什麼是 Heimdall？

Heimdall 是一個專為 Model Context Protocol（MCP）伺服器 與 AI/LLM 應用 打造的開源可觀測性平台。它為開發者、平台團隊與 AI 工程師提供對 AI 基礎設施中工具、資源與提示詞執行情況的深度可見性。

Heimdall 建立在 OpenTelemetry 標準之上，能從你的 MCP 工具與 AI 服務中收集並視覺化即時追蹤、指標與分析資料。它被設計為自我託管（Self-hosted），讓你完全掌握資料，同時能細緻監控延遲、錯誤率、使用模式與工具行為。

透過在 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），並附有簡單易用的 decorator/包裝函式：

  • Python：@trace_mcp_tool() decorator，用於追蹤 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 下載（clone）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()

此 decorator 會為每次呼叫 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 伺服器 或工具：

• 在測試中追蹤每一次對新工具的呼叫。
• 檢視參數與回傳資料，確認邏輯是否正確。
• 快速了解例外（Exception）在哪裡被拋出，以及在何種條件下發生。

這能加速回饋迴圈，縮短在多工具、多步驟工作流程中找出問題所需的時間。

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 支援透過 SDK 參數與環境變數進行環境感知設定。常見模式包括：

• 為不同環境使用不同的 Projects（必要時也可對應不同 Organizations）。
• 在各環境中分別設定 HEIMDALL_ENDPOINT、HEIMDALL_ORG_ID、HEIMDALL_PROJECT_ID、HEIMDALL_SERVICE_NAME、HEIMDALL_ENVIRONMENT 等環境變數。

如此可以邏輯上區隔不同環境的追蹤資料，也方便比較開發、測試與正式環境的行為差異。

Heimdall 能否將追蹤與特定終端使用者關聯？

使用者層級追蹤目前被列為 TODO/規劃中功能。目前所有請求都視為匿名，預設不會將使用者身分與追蹤關聯。未來版本計畫加入使用者追蹤與使用者層級分析能力。