Heimdall

Che cos'è Heimdall?

Heimdall è una piattaforma di osservabilità open-source progettata specificamente per server Model Context Protocol (MCP) e applicazioni AI/LLM. Offre a sviluppatori, team di piattaforma e AI engineer una visibilità profonda su come strumenti, risorse e prompt vengono eseguiti all'interno della loro infrastruttura AI.

Basato sugli standard OpenTelemetry, Heimdall raccoglie e visualizza traces, metriche e analitiche in tempo reale dai tuoi strumenti basati su MCP e dai tuoi servizi AI. È pensato per essere self-hosted, dandoti il pieno controllo dei dati e consentendo un monitoraggio dettagliato di latenza, tassi di errore, pattern di utilizzo e comportamento degli strumenti.

Integrando leggeri SDK nei tuoi server MCP Python o JavaScript/TypeScript, Heimdall rende semplice tracciare ogni chiamata a tool e richiesta di risorsa con modifiche minime al codice esistente. È ideale per team che costruiscono agenti AI, tooling e backend basati su LLM e che vogliono un'osservabilità di livello production senza vincoli di vendor.

Funzionalità principali

• Tracing in tempo reale per server MCP
  Traccia ogni chiamata a tool, accesso a risorsa ed esecuzione legata ai prompt in tempo reale. Heimdall mette in evidenza traces dettagliati che mostrano quando un tool è stato invocato, quanto tempo ha impiegato, quali parametri sono stati passati e se è andato a buon fine o è fallito.

• Dashboard di analisi e visualizzazioni
  Usa la dashboard frontend integrata per analizzare latenza, tassi di errore e pattern di utilizzo dei tuoi servizi AI. Individua rapidamente tool lenti, endpoint che falliscono o picchi di utilizzo anomali.

• Architettura nativa OpenTelemetry
  Heimdall utilizza OTLP/HTTP come protocollo di ingestione ed è completamente allineato agli standard OpenTelemetry. Questo rende più semplice l'integrazione con stack di osservabilità esistenti o l'estensione della tua pipeline di telemetria.

• Integrazione semplice degli SDK per Python e JavaScript/TypeScript
  Heimdall fornisce un SDK Python ufficiale (hmdl) e un SDK JavaScript/TypeScript (hmdl) con semplici decorator/wrapper:

  • Python: decorator @trace_mcp_tool() per tracciare i tool MCP.
  • JS/TS: wrapper traceMCPTool() per funzioni async dei tool.

• Cattura automatica dei parametri
  L'SDK Python ispeziona automaticamente le firme delle funzioni, così i parametri vengono catturati come oggetti con nome (ad es. { "query": "test", "limit": 5 }). L'SDK JS/TS ti permette di specificare paramNames per ottenere lo stesso risultato, rendendo i traces più leggibili e utili per il debugging.

• Deployment self-hosted
  Attualmente Heimdall supporta solo il deployment self-hosted, dandoti pieno controllo su infrastruttura, sicurezza e residenza dei dati. Esegui sia il backend che il frontend sui tuoi server o nell'ambiente di sviluppo locale.

• Modello di organizzazione e progetto
  Heimdall usa una struttura Organizzazione → Progetto:

  • Le Organizzazioni raggruppano progetti e team correlati.
  • I Progetti rappresentano singole applicazioni o ambienti, ognuno con un Project ID univoco per la raccolta dei traces.

• Configurazione basata su variabili d'ambiente
  Configura gli SDK di Heimdall tramite variabili d'ambiente (ad es. HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME, HEIMDALL_ENVIRONMENT, HEIMDALL_ENABLED) per un deployment semplice tra sviluppo, staging e produzione.

• Roadmap futura (funzionalità pianificate)
  Il repository descrive diverse funzionalità in arrivo:

  • User tracking: associare i traces alle identità utente per analitiche a livello di utente (attualmente tutte le richieste sono anonime).
  • Valutazione LLM: scoring integrato della qualità del modello e workflow di valutazione umana.
  • Managed cloud host: opzione di deployment cloud gestito per i team che preferiscono non effettuare il self-hosting.

Come usare Heimdall

Usare Heimdall richiede tre passaggi principali: eseguire la piattaforma, creare un'organizzazione e un progetto e integrare gli SDK nei tuoi server MCP o nelle tue applicazioni AI.

1. Impostare i prerequisiti

Assicurati di avere le dipendenze di runtime richieste:

• Node.js 18+ (per backend e frontend di Heimdall)
• Python 3.9+ (se prevedi di usare l'SDK Python)

Clona il repository Heimdall da GitHub e accedi alla cartella del progetto.

2. Avviare il backend

Dalla root del progetto:

cd backend
npm install
npm run dev

Questo avvia il backend Heimdall, che espone un endpoint OTLP/HTTP (default: http://localhost:4318) per l'ingestione dei traces.

3. Avviare il frontend

In un altro terminale:

cd frontend
npm install
npm run dev

Il frontend è in genere disponibile su http://localhost:5173, fornendo la web UI per organizzazioni, progetti e analitiche.

4. Creare un account, un'organizzazione e un progetto

1. Apri http://localhost:5173 in un browser.
2. Crea un account usando la tua email e una password.
3. Crea un'Organization per raggruppare i tuoi progetti.
4. Crea un Project all'interno dell'organizzazione. Ogni progetto riceve un Project ID univoco usato per associare i traces in ingresso.

Poi vai alla pagina Settings del tuo progetto per trovare:

• Organization ID
• Project ID

Userai questi valori nella configurazione dei tuoi SDK.

5. Integrare l'SDK Python

Installa il package Python:

pip install hmdl

Esempio di integrazione di base:

from hmdl import HeimdallClient, trace_mcp_tool

# Inizializza il client
client = HeimdallClient(
    endpoint="http://localhost:4318",
    org_id="your-org-id",       # Dalla pagina Settings
    project_id="your-project-id", # Dalla pagina 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()

Il decorator crea automaticamente traces per ogni invocazione di search_tool, catturando argomenti e metadati di esecuzione.

6. Integrare l'SDK JavaScript/TypeScript

Installa il package JS/TS:

npm install hmdl

Esempio di integrazione di base (stile TypeScript):

import { HeimdallClient, traceMCPTool } from 'hmdl';

const client = new HeimdallClient({
  endpoint: "http://localhost:4318",
  orgId: "your-org-id",       // Dalla pagina Settings
  projectId: "your-project-id", // Dalla pagina 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. Configurare tramite variabili d'ambiente (opzionale)

Puoi configurare il client Heimdall usando variabili d'ambiente invece di inserire i valori nel codice:

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"

Poi inizializza il client senza argomenti:

# Python
from hmdl import HeimdallClient
client = HeimdallClient()

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

Una volta integrati, i tuoi tool MCP emetteranno telemetria verso il backend Heimdall e potrai analizzare traces e metriche nella web UI.

Casi d'uso

1. Osservabilità per agenti AI e toolchain

I team che costruiscono agenti AI complessi che si appoggiano a tool MCP devono capire come ogni tool si comporta in scenari reali. Heimdall offre:

• Monitoraggio della latenza e degli errori per singolo tool.
• Visibilità su quali tool vengono usati più frequentemente.
• Insight su come prompt e risorse vengono accessi tramite questi tool.

Questo aiuta i team a ottimizzare la toolchain, deprecare i tool poco usati e fare debug del comportamento degli agenti in modo più efficace.

2. Monitoraggio in produzione per backend basati su LLM

Per le organizzazioni che eseguono API basate su LLM o microservizi AI in produzione, Heimdall funge da livello di osservabilità fondamentale:

• Monitora throughput delle richieste e tempi di risposta.
• Individua percorsi lenti causati da dipendenze esterne o da tool specifici.
• Rileva picchi di errore o regressioni dopo i deployment.

Con Heimdall integrato tramite OpenTelemetry, puoi allineare l'osservabilità dell'AI con il tuo stack di monitoraggio più ampio.

3. Sviluppo e debugging di server MCP

Durante lo sviluppo, Heimdall aiuta gli ingegneri a fare debug di nuovi server MCP o tool:

• Traccia ogni chiamata a un nuovo tool durante i test.
• Ispeziona parametri e dati restituiti per verificarne la correttezza.
• Vedi rapidamente dove vengono generate eccezioni e in quali condizioni.

Questo accelera i cicli di feedback e riduce il tempo necessario per identificare problemi in workflow multi-tool e multi-step.

4. Team di piattaforma AI interna e infrastruttura

I team di piattaforma che forniscono infrastruttura AI interna a più team di prodotto possono usare Heimdall per offrire un'osservabilità standardizzata:

• Crea progetti separati per ogni applicazione o tenant.
• Monitora pattern di utilizzo e performance a livello di organizzazione.
• Usa il futuro tracking a livello di utente (funzionalità pianificata) per comprendere il consumo per team o cliente.

Questo abilita un migliore capacity planning, modelli di chargeback/showback e una maggiore affidabilità del servizio.

5. Ambienti attenti alla privacy o regolamentati

Poiché Heimdall è self-hosted e open source, è particolarmente adatto a organizzazioni che operano in ambienti altamente regolamentati o sensibili alla sicurezza:

• Mantieni tutti i traces e i metadati all'interno della tua infrastruttura.
• Allinea i deployment ai requisiti interni di sicurezza e compliance.
• Personalizza la piattaforma o integrala con strumenti di monitoring e alerting esistenti.

FAQ

Heimdall è gratuito da usare?

Sì. Heimdall è rilasciato sotto licenza MIT, il che lo rende gratuito e open source sia per uso personale che commerciale. Sei responsabile dell'hosting e dell'esecuzione della piattaforma sulla tua infrastruttura. La roadmap menziona anche una possibile offerta cloud gestita in futuro, ma il progetto core è open source.

Quali tecnologie e standard utilizza Heimdall?

Heimdall è basato su OpenTelemetry e utilizza il protocollo OTLP/HTTP (porta predefinita 4318) per l'ingestione dei dati di telemetria. Backend e frontend sono servizi basati su Node.js e gli SDK client ufficiali sono disponibili per Python e JavaScript/TypeScript.

Quali ambienti e linguaggi sono supportati?

Attualmente Heimdall fornisce SDK ufficiali per:

• Python (tramite il package hmdl; richiede Python 3.9+)
• JavaScript/TypeScript (tramite il package npm hmdl; funziona con Node.js 18+)

Poiché Heimdall parla OpenTelemetry/OTLP, puoi potenzialmente integrare altri linguaggi usando le librerie standard OpenTelemetry, anche se l'esperienza più fluida è con gli SDK ufficiali focalizzati su MCP.

Devo per forza fare il self-hosting di Heimdall?

Sì, al momento Heimdall è progettato come piattaforma self-hosted. Esegui tu stesso sia i servizi backend che frontend (ad es. su macchine locali, VM, Kubernetes o il tuo provider di hosting preferito). La roadmap del progetto menziona un managed cloud host server come possibile evoluzione, ma non fa parte della release attuale.

Come configuro più ambienti (dev, staging, produzione)?

Heimdall supporta una configurazione consapevole dell'ambiente tramite parametri degli SDK e variabili d'ambiente. Uno schema comune è:

• Usare Projects diversi (e possibilmente Organizations diverse) per i vari ambienti.
• Impostare variabili d'ambiente come HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME e HEIMDALL_ENVIRONMENT separatamente in ogni ambiente.

Questo mantiene i traces separati logicamente e rende semplice confrontare il comportamento tra sviluppo, staging e produzione.

Heimdall può associare i traces a utenti finali specifici?

Il tracking a livello di utente è indicato come funzionalità TODO/in roadmap. Al momento tutte le richieste sono trattate come anonime e le identità utente non vengono associate ai traces in modo predefinito. Il progetto prevede di aggiungere in futuro il supporto per il tracking degli utenti e per analitiche a livello di utente.