AI导哈

可观测性平台

Heimdall是一个开源的可观测性平台，专为监控MCP服务器和AI/LLM应用设计，提供实时追踪、指标和仪表盘分析功能。

  • by delta0-inc
  • TypeScript
  • 本地部署
  • 29 星标
  • 更新于
在 GitHub 查看 hmdl-inc/heimdall

使用说明

海姆达尔

MCP服务器和人工智能应用程序的开源可观察性平台

概述

Heimdall是一个全面的可观察性平台，专为监控模型上下文协议（MCP）服务器和AI/LLM应用程序而设计。基于OpenTetry标准，它为您的AI基础设施提供实时跟踪、指标和洞察。

主要特点

  • 🔍 实时跟踪 -跟踪每个工具调用、资源访问和提示执行
  • 📊 仪表板分析 -可视化延迟、错误率和使用模式
  • 🔌 轻松集成 -Python和JavaScript/TypeScript的简单SDK装饰器
  • 🏠 自托管 -完全在您自己的基础设施上运行
  • 📈 OpenTetry原生 -基于行业标准的可观察性协议

待办事项

  • [ ] 跟踪用户 -将跟踪与用户身份相关联，以进行用户级分析（目前所有请求都显示为匿名）。
  • [ ] 评估 -LLM评估和质量评分，包括人工注释。
  • [ ] 添加云主机服务器 -托管云部署。

建筑

目前我们只支持自托管部署。架构如下：

┌─────────────────┐     OTLP/HTTP      ┌─────────────────┐
│   MCP Server    │ ──────────────────▶│  Heimdall       │
│   + SDK         │    Port 4318       │  Backend        │
└─────────────────┘                    └────────┬────────┘
                                                │
                                                │ REST API
                                                │
                                       ┌────────▼────────┐
                                       │  Heimdall       │
                                       │  Frontend       │
                                       │  Port 5173      │
                                       └─────────────────┘

快速开始

📖 有关详细的设置说明，请参阅 QUICKSTART.md

先决条件

  • Node.js 18+
  • Python 3.9+（适用于Python SDK）

1.启动后端

cd backend
npm install
npm run dev

2.启动前端

cd frontend
npm install
npm run dev

3.创建组织和项目

  1. 导航至http://localhost:5173
  2. 创建账户 使用您的电子邮件和密码
  3. 创建组织 -这将您的项目分组在一起
  4. 创建项目 -每个项目都有一个唯一的ID用于跟踪收集

4.获取您的配置

创建组织和项目后，转到 设置 查找：

  • 组织ID -您的组织标识符
  • 项目ID -您的项目标识符

您需要这些ID来配置SDK。

SDK集成

Heimdall提供用于检测MCP服务器的SDK：

SDK 软件包 安装
python hmdl pip install hmdl
JavaScript/TypeScript hmdl npm install hmdl

Python示例

from hmdl import HeimdallClient, trace_mcp_tool

# Initialize client with your organization and project IDs
client = HeimdallClient(
    endpoint="http://localhost:4318",
    org_id="your-org-id",           # From Settings page
    project_id="your-project-id",   # From Settings page
    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()

备注：Python SDK使用自检自动捕获参数名称。输入显示为命名对象： {"query": "test", "limit": 5}.

JavaScript/TypeScript示例

import { HeimdallClient, traceMCPTool } from 'hmdl';

// Initialize client with your organization and project IDs
const client = new HeimdallClient({
  endpoint: "http://localhost:4318",
  orgId: "your-org-id",           // From Settings page
  projectId: "your-project-id",   // From Settings page
  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();

备注：使用 paramNames 将输入显示为命名对象的选项（例如。， {"query": "test", "limit": 5})而不是数组(["test", 5]).

使用环境变量

您还可以使用环境变量配置SDK：

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
client = HeimdallClient()

// JavaScript/TypeScript
const client = new HeimdallClient();

配置

环境变量

变量 描述 默认值
HEIMDALL_ENDPOINT 后端OTLP端点 http://localhost:4318
HEIMDALL_ORG_ID 来自仪表板的组织ID default
HEIMDALL_PROJECT_ID 跟踪分组的项目ID default
HEIMDALL_SERVICE_NAME 跟踪中的服务名称 mcp-server
HEIMDALL_ENVIRONMENT 环境标签 development
HEIMDALL_ENABLED 启用/禁用跟踪 true
HEIMDALL_API_KEY 用于身份验证的API密钥 -
HEIMDALL_DEBUG 启用调试日志记录 false
HEIMDALL_BATCH_SIZE 批处理的跨度数量 100
HEIMDALL_FLUSH_INTERVAL_MS 刷新间隔（毫秒） 5000

客户端配置选项

选项 Python JavaScript 描述
端点 endpoint endpoint Heimdall后端URL
组织ID org_id orgId 您的组织ID
项目ID project_id projectId 您的项目ID
服务名称 service_name serviceName 您的服务名称
环境 environment environment 部署环境
API密钥 api_key apiKey 可选API密钥
调试 debug debug 启用调试日志记录

包装/装饰选项

trace_mcp_tool / traceMCPTool

选项 Python JavaScript 描述
姓名 name （arg） name 自定义跨度名称（默认为函数名称）
参数名称 不适用（自动） paramNames 用于输入显示的参数名称数组
捕获输入 不适用 captureInput 是否捕获输入参数（默认值：true）
捕获输出 N/A captureOutput 是否捕获返回值（默认值：true）

observe （通用）

选项 Python JavaScript 描述
姓名 name name 自定义跨度名称（默认为函数名称）
捕获输入 capture_input captureInput 是否捕获输入参数（默认值：true）
捕获输出 capture_output captureOutput 是否捕获返回值（默认值：true）

项目结构

heimdall/
├── backend/          # OTLP receiver and API server
├── frontend/         # React dashboard
├── tests/            # SDK integration tests
├── QUICKSTART.md     # Detailed setup guide
└── README.md         # This file

heimdall-python/      # Python SDK
heimdall-js/          # JavaScript/TypeScript SDK

运行测试

测试SDK与后端的集成：

# Python SDK test
cd tests
source .venv/bin/activate
python test_python_sdk.py

# JavaScript SDK test
cd tests
npm run test:js

文档

贡献

欢迎投稿！请随时提交拉取请求。

支持与联系

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

相关 MCP