Heimdall

O que é o Heimdall?

Heimdall é uma plataforma de observabilidade open-source criada especificamente para servidores Model Context Protocol (MCP) e aplicações de IA/LLM. Ele oferece a desenvolvedores, equipes de plataforma e engenheiros de IA visibilidade profunda sobre como ferramentas, recursos e prompts estão sendo executados dentro da infraestrutura de IA.

Baseado nos padrões do OpenTelemetry, o Heimdall coleta e visualiza rastros (traces), métricas e análises em tempo real das suas ferramentas baseadas em MCP e dos seus serviços de IA. Ele foi projetado para ser self-hosted, colocando você no controle total dos dados e permitindo monitoramento detalhado de latência, taxas de erro, padrões de uso e comportamento das ferramentas.

Ao integrar SDKs leves nos seus servidores MCP em Python ou JavaScript/TypeScript, o Heimdall torna fácil rastrear cada chamada de ferramenta e cada requisição de recurso com mudanças mínimas no código existente. É ideal para equipes que constroem agentes de IA, ferramentas e backends baseados em LLM e que desejam observabilidade em nível de produção sem vendor lock-in.

Principais recursos

• Rastreamento em tempo real para servidores MCP
  Acompanhe cada chamada de ferramenta, acesso a recurso e execução relacionada a prompts em tempo real. O Heimdall exibe rastros detalhados que mostram quando uma ferramenta foi invocada, quanto tempo levou, quais parâmetros foram passados e se a execução teve sucesso ou falhou.

• Dashboard de análises e visualizações
  Use o dashboard frontend integrado para analisar latência, taxas de erro e padrões de uso em seus serviços de IA. Identifique rapidamente ferramentas lentas, endpoints com falhas ou picos de uso incomuns.

• Arquitetura nativa OpenTelemetry
  O Heimdall usa OTLP/HTTP como protocolo de ingestão e está totalmente alinhado aos padrões OpenTelemetry. Isso facilita a integração com stacks de observabilidade existentes ou a extensão do seu pipeline de telemetria.

• Integração simples de SDKs para Python e JavaScript/TypeScript
  O Heimdall fornece um SDK oficial para Python (hmdl) e um SDK para JavaScript/TypeScript (hmdl) com decorators/wrappers simples:

  • Python: decorator @trace_mcp_tool() para rastrear ferramentas MCP.
  • JS/TS: wrapper traceMCPTool() para funções assíncronas de ferramentas.

• Captura automática de parâmetros
  O SDK de Python inspeciona automaticamente as assinaturas das funções, para que os parâmetros sejam capturados como objetos nomeados (por exemplo, { "query": "test", "limit": 5 }). O SDK de JS/TS permite que você especifique paramNames para obter o mesmo resultado, tornando os rastros mais legíveis e úteis para depuração.

• Implantação self-hosted
  Atualmente, o Heimdall suporta apenas implantação self-hosted, dando a você controle total sobre infraestrutura, segurança e residência dos dados. Você executa tanto o backend quanto o frontend em seus próprios servidores ou no ambiente de desenvolvimento local.

• Modelo de organização e projeto
  O Heimdall utiliza uma estrutura Organização → Projeto:

  • Organizações agrupam projetos e equipes relacionados.
  • Projetos representam aplicações ou ambientes individuais, cada um com um Project ID exclusivo para coleta de rastros.

• Configuração baseada em variáveis de ambiente
  Configure os SDKs do Heimdall por meio de variáveis de ambiente (por exemplo, HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME, HEIMDALL_ENVIRONMENT, HEIMDALL_ENABLED) para facilitar a implantação em desenvolvimento, staging e produção.

• Roadmap futuro (funcionalidades planejadas)
  O repositório descreve vários recursos em desenvolvimento:

  • Rastreamento de usuários: associar rastros a identidades de usuário para análises em nível de usuário (atualmente todas as requisições são anônimas).
  • Avaliação de LLM: pontuação integrada de qualidade de modelo e fluxos de trabalho de avaliação humana.
  • Hospedagem em nuvem gerenciada: opção de implantação em nuvem gerenciada para equipes que preferem não fazer self-hosting.

Como usar o Heimdall

Usar o Heimdall envolve três etapas principais: executar a plataforma, criar uma organização e um projeto e integrar os SDKs aos seus servidores MCP ou aplicações de IA.

1. Configurar os pré-requisitos

Garanta que você tenha as dependências de runtime necessárias:

• Node.js 18+ (para backend e frontend do Heimdall)
• Python 3.9+ (se você pretende usar o SDK de Python)

Clone o repositório do Heimdall a partir do GitHub e navegue até a pasta do projeto.

2. Iniciar o backend

A partir da raiz do projeto:

cd backend
npm install
npm run dev

Isso inicia o backend do Heimdall, que expõe um endpoint OTLP/HTTP (padrão: http://localhost:4318) para ingestão de rastros.

3. Iniciar o frontend

Em um terminal separado:

cd frontend
npm install
npm run dev

O frontend normalmente fica disponível em http://localhost:5173, fornecendo a interface web para organizações, projetos e análises.

4. Criar uma conta, organização e projeto

1. Abra http://localhost:5173 em um navegador.
2. Crie uma conta usando seu e-mail e senha.
3. Crie uma Organization para agrupar seus projetos.
4. Crie um Project dentro da organização. Cada projeto recebe um Project ID exclusivo usado para associar os rastros recebidos.

Em seguida, acesse a página de Settings do seu projeto para encontrar:

• Organization ID
• Project ID

Você usará esses valores na configuração dos SDKs.

5. Integrar o SDK de Python

Instale o pacote de Python:

pip install hmdl

Exemplo básico de integração:

from hmdl import HeimdallClient, trace_mcp_tool

# Inicializa o client
client = HeimdallClient(
    endpoint="http://localhost:4318",
    org_id="your-org-id",       # A partir de Settings
    project_id="your-project-id", # A partir de 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()

O decorator cria automaticamente rastros para cada invocação de search_tool, capturando argumentos e metadados de execução.

6. Integrar o SDK de JavaScript/TypeScript

Instale o pacote JS/TS:

npm install hmdl

Exemplo básico de integração (estilo TypeScript):

import { HeimdallClient, traceMCPTool } from 'hmdl';

const client = new HeimdallClient({
  endpoint: "http://localhost:4318",
  orgId: "your-org-id",       // A partir de Settings
  projectId: "your-project-id", // A partir de 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. Configurar via variáveis de ambiente (opcional)

Você pode configurar o client do Heimdall usando variáveis de ambiente em vez de codificar os valores:

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"

Em seguida, inicialize o client sem argumentos:

# Python
from hmdl import HeimdallClient
client = HeimdallClient()

// JavaScript/TypeScript
import { HeimdallClient } from 'hmdl';
const client = new HeimdallClient();

Depois de integrado, suas ferramentas MCP passarão a emitir telemetria para o backend do Heimdall, e você poderá analisar rastros e métricas na interface web.

Casos de uso

1. Observabilidade para agentes de IA e toolchains

Equipes que constroem agentes de IA complexos que dependem de ferramentas MCP precisam entender como cada ferramenta se comporta em cargas de trabalho reais. O Heimdall oferece:

• Acompanhamento de latência e erros por ferramenta.
• Visibilidade sobre quais ferramentas são usadas com maior frequência.
• Insights sobre como prompts e recursos são acessados por meio dessas ferramentas.

Isso ajuda as equipes a otimizar a toolchain, descontinuar ferramentas pouco utilizadas e depurar o comportamento dos agentes com mais eficiência.

2. Monitoramento em produção para backends com LLM

Para organizações que executam APIs baseadas em LLM ou microsserviços de IA em produção, o Heimdall atua como uma camada crítica de observabilidade:

• Monitore throughput de requisições e tempos de resposta.
• Localize caminhos lentos causados por dependências externas ou ferramentas específicas.
• Detecte picos de erros ou regressões após deploys.

Com o Heimdall integrado via OpenTelemetry, você pode alinhar a observabilidade de IA ao seu stack de monitoramento mais amplo.

3. Desenvolvimento e depuração de servidores MCP

Durante o desenvolvimento, o Heimdall ajuda engenheiros a depurar novos servidores MCP ou novas ferramentas:

• Rastreie cada chamada para uma nova ferramenta durante os testes.
• Inspecione parâmetros e dados retornados para verificar a correção.
• Veja rapidamente onde exceções são lançadas e em quais condições.

Isso acelera ciclos de feedback e reduz o tempo necessário para identificar problemas em fluxos de trabalho com múltiplas ferramentas e múltiplas etapas.

4. Equipes internas de plataforma e infraestrutura de IA

Equipes de plataforma que fornecem infraestrutura de IA interna para múltiplas equipes de produto podem usar o Heimdall para oferecer observabilidade padronizada:

• Crie projetos separados para cada aplicação ou tenant.
• Monitore padrões de uso e desempenho em toda a organização.
• Utilize o futuro rastreamento em nível de usuário (planejado) para entender o consumo por equipe ou cliente.

Isso possibilita um melhor planejamento de capacidade, modelos de chargeback/showback e maior confiabilidade de serviço.

5. Ambientes com foco em privacidade ou regulados

Como o Heimdall é self-hosted e open source, ele é especialmente adequado para organizações que operam em ambientes altamente regulados ou sensíveis à segurança:

• Mantenha todos os rastros e metadados dentro da sua própria infraestrutura.
• Alinhe as implantações aos requisitos internos de segurança e conformidade.
• Personalize a plataforma ou integre-a às ferramentas de monitoramento e alerta existentes.

FAQ

O Heimdall é gratuito para uso?

Sim. O Heimdall é distribuído sob a licença MIT, o que o torna gratuito e open source tanto para uso pessoal quanto comercial. Você é responsável por hospedar e executar a plataforma na sua própria infraestrutura. A roadmap também menciona uma possível oferta em nuvem gerenciada no futuro, mas o projeto principal é open source.

Quais tecnologias e padrões o Heimdall utiliza?

O Heimdall é construído sobre OpenTelemetry e usa o protocolo OTLP/HTTP (porta padrão 4318) para ingestão de dados de telemetria. O backend e o frontend são serviços baseados em Node.js, e os SDKs cliente oficiais estão disponíveis para Python e JavaScript/TypeScript.

Quais ambientes e linguagens são suportados?

Atualmente, o Heimdall fornece SDKs oficiais para:

• Python (por meio do pacote hmdl; requer Python 3.9+)
• JavaScript/TypeScript (por meio do pacote npm hmdl; roda com Node.js 18+)

Como o Heimdall fala OpenTelemetry/OTLP, você pode potencialmente integrar outras linguagens usando bibliotecas OpenTelemetry padrão, embora a experiência mais fluida seja com os SDKs oficiais focados em MCP.

Eu preciso necessariamente fazer self-hosting do Heimdall?

Sim, no momento o Heimdall foi projetado como uma plataforma self-hosted. Você executa tanto os serviços de backend quanto de frontend (por exemplo, em máquinas locais, VMs, Kubernetes ou no provedor de hospedagem de sua preferência). A roadmap do projeto menciona um managed cloud host server como futuro aprimoramento, mas ele não faz parte da versão atual.

Como configuro múltiplos ambientes (dev, staging, produção)?

O Heimdall oferece suporte a configuração sensível ao ambiente por meio de parâmetros dos SDKs e variáveis de ambiente. Um padrão comum é:

• Usar Projects diferentes (e possivelmente Organizations diferentes) para cada ambiente.
• Definir variáveis como HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME e HEIMDALL_ENVIRONMENT separadamente em cada ambiente.

Isso mantém os rastros logicamente separados e facilita a comparação de comportamento entre desenvolvimento, staging e produção.

O Heimdall pode associar rastros a usuários finais específicos?

O rastreamento em nível de usuário está listado como uma funcionalidade TODO/em roadmap. Atualmente, todas as requisições são tratadas como anônimas, e identidades de usuário não são associadas aos rastros por padrão. O projeto planeja adicionar suporte a rastreamento de usuários e análises em nível de usuário em versões futuras.