Heimdall

Heimdall란 무엇인가요?

Heimdall는 Model Context Protocol(MCP) 서버와 AI/LLM 애플리케이션을 위해 설계된 오픈 소스 가시성(Observability) 플랫폼입니다. 개발자, 플랫폼 팀, AI 엔지니어가 AI 인프라 내부에서 도구, 리소스, 프롬프트가 어떻게 실행되는지 깊이 있게 파악할 수 있도록 도와줍니다.

Heimdall는 OpenTelemetry 표준을 기반으로, MCP 기반 도구와 AI 서비스에서 발생하는 실시간 트레이스, 메트릭, 분석 데이터를 수집하고 시각화합니다. 셀프 호스팅을 전제로 설계되어 데이터에 대한 완전한 통제권을 유지하면서 지연 시간, 에러율, 사용 패턴, 도구 동작을 세밀하게 모니터링할 수 있습니다.

가벼운 SDK를 Python 또는 JavaScript/TypeScript 기반 MCP 서버에 통합하면, 기존 코드 변경을 최소화하면서 각 도구 호출과 리소스 요청을 손쉽게 추적할 수 있습니다. 벤더 종속성 없이 프로덕션 수준의 관측 가능성을 확보하려는 AI 에이전트, 도구 체인, LLM 기반 백엔드를 개발하는 팀에 특히 적합합니다.

주요 기능

• MCP 서버용 실시간 트레이싱
  모든 도구 호출, 리소스 접근, 프롬프트 관련 실행을 실시간으로 추적합니다. Heimdall는 도구가 언제 호출되었는지, 얼마나 걸렸는지, 어떤 파라미터가 전달되었는지, 성공/실패 여부를 보여주는 상세 트레이스를 제공합니다.

• 대시보드 분석 및 시각화
  내장 프론트엔드 대시보드를 통해 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 구조를 사용합니다:

  • Organization은 관련 프로젝트와 팀을 그룹화합니다.
  • Project는 개별 애플리케이션 또는 환경을 나타내며, 트레이스 수집을 위한 고유한 Project ID를 가집니다.

• 환경 기반 설정
  환경 변수(예: HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME, HEIMDALL_ENVIRONMENT, HEIMDALL_ENABLED)를 통해 Heimdall SDK를 설정할 수 있어, 개발·스테이징·프로덕션 환경 간 배포를 쉽게 관리할 수 있습니다.

• 향후 로드맵(예정 기능)
  저장소에는 다음과 같은 예정 기능들이 나와 있습니다:

  • 사용자 추적: 트레이스를 사용자 ID와 연계하여 사용자 단위 분석 제공(현재는 모든 요청이 익명 처리).
  • 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**에서 실행되며, 조직, 프로젝트, 분석을 위한 웹 UI를 제공합니다.

4. 계정, 조직, 프로젝트 생성

1. 브라우저에서 http://localhost:5173에 접속합니다.
2. 이메일과 비밀번호로 계정을 생성합니다.
3. 프로젝트를 그룹화할 Organization을 생성합니다.
4. 해당 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. 환경 변수로 설정하기(선택 사항)

클라이언트 설정 값을 하드코딩하는 대신 환경 변수로 구성할 수 있습니다:

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 백엔드로 텔레메트리를 전송하며, 웹 UI에서 트레이스와 메트릭을 분석할 수 있습니다.

활용 사례

1. AI 에이전트 및 툴체인 관측

복잡한 AI 에이전트를 구축하는 팀은 MCP 도구가 실제 workload에서 어떻게 동작하는지 이해해야 합니다. Heimdall는 다음과 같은 기능을 제공합니다:

• 도구별 지연 시간 추적 및 에러 모니터링
• 어떤 도구가 가장 자주 사용되는지에 대한 가시성
• 프롬프트와 리소스가 각 도구를 통해 어떻게 접근되는지에 대한 인사이트

이를 통해 팀은 툴체인을 최적화하고, 사용 빈도가 낮은 도구를 폐기하며, 에이전트 동작을 더 효과적으로 디버깅할 수 있습니다.

2. LLM 기반 백엔드의 프로덕션 모니터링

프로덕션 환경에서 LLM 기반 API나 AI 마이크로서비스를 운영하는 조직에게 Heimdall는 중요한 관측 레이어 역할을 합니다:

• 요청 처리량과 응답 시간을 모니터링
• 외부 의존성이나 특정 도구 때문에 발생하는 느린 경로를 정확히 파악
• 배포 이후 에러 급증 또는 회귀(regression) 탐지

Heimdall를 OpenTelemetry와 함께 통합하면 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 파라미터와 환경 변수를 통해 환경별 구성을 지원합니다. 일반적인 패턴은 다음과 같습니다:

• 환경별로 서로 다른 Project(필요 시 Organization도)를 사용
• 각 환경에서 HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME, HEIMDALL_ENVIRONMENT 등의 환경 변수를 별도로 설정

이를 통해 환경별 트레이스를 논리적으로 분리하고, 개발·스테이징·프로덕션 간 동작을 쉽게 비교할 수 있습니다.

Heimdall는 개별 최종 사용자와 트레이스를 연계할 수 있나요?

사용자 단위 추적은 현재 TODO/로드맵 기능으로 명시되어 있습니다. 현재 버전에서는 모든 요청이 익명으로 처리되며, 트레이스에 사용자 ID가 기본적으로 연결되지 않습니다. 향후 릴리스에서 사용자 추적 및 사용자 단위 분석 기능을 제공할 계획입니다.