Heimdall

Heimdall とは？

Heimdall は、Model Context Protocol（MCP）サーバー と AI/LLM アプリケーション 専用に設計されたオープンソースのオブザーバビリティ・プラットフォームです。開発者、プラットフォームチーム、AI エンジニアに対し、AI インフラ内部でツールやリソース、プロンプトがどのように実行されているかを深く可視化します。

OpenTelemetry 規格に基づいて構築されており、MCP ベースのツールや AI サービスから リアルタイムのトレース、メトリクス、分析データ を収集・可視化します。Heimdall は**自前運用（セルフホスト）**を前提としており、データを完全に自分たちで管理しつつ、レイテンシ、エラー率、利用パターン、ツールの挙動を詳細に監視できます。

軽量な SDK を Python や JavaScript/TypeScript 製の MCP サーバーに組み込むだけで、既存コードへの変更を最小限に抑えながら、各ツール呼び出しやリソースリクエストをトレースできます。ベンダーロックインなしで本番運用レベルのオブザーバビリティを求める、AI エージェントやツール群、LLM バックエンドを構築しているチームに最適です。

主な特長

• MCP サーバー向けリアルタイムトレーシング
  すべてのツール呼び出し、リソースアクセス、プロンプト関連の実行をリアルタイムで追跡します。ツールがいつ呼び出され、処理にどれだけ時間がかかり、どのようなパラメータが渡され、成功したか失敗したかまで、詳細なトレースを可視化します。

• ダッシュボード分析と可視化
  組み込みのフロントエンド・ダッシュボードを使い、AI サービス全体のレイテンシ、エラー率、利用パターンを分析できます。遅いツールやエラーが発生しているエンドポイント、異常なトラフィック急増などを素早く検知できます。

• OpenTelemetry ネイティブなアーキテクチャ
  Heimdall は OTLP/HTTP をインジェスト用プロトコルとして採用しており、OpenTelemetry 規格と完全に整合しています。既存のオブザーバビリティスタックとの統合や、テレメトリーパイプラインの拡張が容易です。

• Python と JavaScript/TypeScript 向けの簡単な SDK 連携
  Heimdall は公式 Python SDK（hmdl） と JavaScript/TypeScript SDK（hmdl） を提供し、シンプルなデコレータ／ラッパーで利用できます：

  • Python：MCP ツールをトレースする @trace_mcp_tool() デコレータ。
  • 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）で設定でき、開発・ステージング・本番環境へのデプロイを容易にします。

• ロードマップ（予定されている機能）
  リポジトリには、今後追加予定の機能がいくつか示されています：

  • ユーザー追跡：トレースをユーザー ID と関連づけ、ユーザー単位の分析を可能に（現状すべてのリクエストは匿名）。
  • LLM 評価：モデル品質スコアリングや人手評価ワークフローの内蔵。
  • マネージドクラウドホスト：セルフホストしたくないチーム向けのマネージドクラウド版オプション。

Heimdall の使い方

Heimdall を利用するには、プラットフォームを起動する、組織とプロジェクトを作成する、SDK を MCP サーバーや AI アプリに組み込むという 3 つのステップがあります。

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 UI を提供します。

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 UI 上でトレースやメトリクスを分析できるようになります。

ユースケース

1. AI エージェントとツールチェーンのオブザーバビリティ

複雑な AI エージェント を構築し、MCP ツールに依存しているチームは、各ツールが実際のワークロードでどのように動作しているかを把握する必要があります。Heimdall は次のような情報を提供します：

• ツール単位のレイテンシ追跡とエラーモニタリング。
• どのツールが最も頻繁に使われているかの可視化。
• プロンプトやリソースがツール経由でどのようにアクセスされているかのインサイト。

これにより、ツールチェーンの最適化、利用の少ないツールの整理（廃止）、エージェント挙動の効率的なデバッグが可能になります。

2. LLM バックエンドの本番監視

LLM ベースの API や AI マイクロサービス を本番運用している組織にとって、Heimdall は重要なオブザーバビリティレイヤーとして機能します：

• リクエストスループットとレスポンスタイムを監視。
• 外部依存や特定ツールが原因となる遅いパスを特定。
• デプロイ後のエラー急増やリグレッションを検知。

OpenTelemetry 経由で Heimdall を統合することで、AI のオブザーバビリティを既存の監視スタックと一貫させることができます。

3. MCP サーバーの開発・デバッグ

開発中、Heimdall はエンジニアが 新しい MCP サーバー やツールをデバッグするのに役立ちます：

• テスト中に、新しいツールへのすべての呼び出しをトレース。
• パラメータや返却データを確認し、動作の正しさを検証。
• 例外がどこで、どのような条件で発生しているかを素早く把握。

これによりフィードバックサイクルが短縮され、多数のツールやステップからなるワークフローにおける問題特定時間を削減できます。

4. 社内 AI プラットフォーム／インフラチーム

複数のプロダクトチームに 社内 AI インフラ を提供しているプラットフォームチームは、Heimdall を用いて標準化されたオブザーバビリティを提供できます：

• アプリケーションやテナントごとに個別プロジェクトを作成。
• 組織全体の利用状況やパフォーマンス傾向を監視。
• 今後追加予定のユーザー単位トラッキング機能を利用し、チームや顧客ごとの利用量を把握。

これにより、キャパシティプランニングやチャージバック／ショーバックモデル、サービス信頼性の向上に役立ちます。

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 は セルフホスト型 プラットフォームとして設計されています。バックエンド・フロントエンドの両方を（ローカルマシン、VM、Kubernetes、任意のクラウドプロバイダなど）自前で運用します。ロードマップには マネージドクラウドホスト の構想もありますが、現行リリースには含まれていません。

複数環境（開発・ステージング・本番）をどのように切り分ければよいですか？

Heimdall は SDK パラメータと環境変数を通じて、環境ごとの設定をサポートしています。一般的なパターンは以下のとおりです：

• 環境ごとに異なる Projects（必要に応じて Organizations も）を用意する。
• 各環境で HEIMDALL_ENDPOINT、HEIMDALL_ORG_ID、HEIMDALL_PROJECT_ID、HEIMDALL_SERVICE_NAME、HEIMDALL_ENVIRONMENT などの環境変数をそれぞれ設定する。

これにより、環境ごとにトレースを論理的に分離でき、開発・ステージング・本番の挙動を比較しやすくなります。

Heimdall は特定のエンドユーザーとトレースを紐づけられますか？

ユーザー単位のトラッキングは、現在 TODO／ロードマップ上の機能 として位置づけられています。現状ではすべてのリクエストは匿名として扱われ、ユーザー ID とトレースはデフォルトでは関連づけられていません。将来のバージョンでは、ユーザー追跡およびユーザー単位分析への対応が計画されています。