Heimdall

Qu’est-ce que Heimdall ?

Heimdall est une plateforme d’observabilité open source conçue spécifiquement pour les serveurs Model Context Protocol (MCP) et les applications d’IA/LLM. Elle offre aux développeurs, aux équipes plateforme et aux ingénieurs IA une visibilité approfondie sur la façon dont les outils, ressources et prompts sont exécutés au sein de leur infrastructure d’IA.

Basé sur les standards OpenTelemetry, Heimdall collecte et visualise en temps réel des traces, métriques et analyses provenant de vos outils MCP et services d’IA. La plateforme est pensée pour être auto‑hébergée, ce qui vous donne un contrôle total sur vos données tout en permettant une surveillance fine de la latence, des taux d’erreur, des schémas d’utilisation et du comportement des outils.

En intégrant des SDK légers dans vos serveurs MCP en Python ou JavaScript/TypeScript, Heimdall facilite le traçage de chaque appel d’outil et de chaque requête de ressource, avec un minimum de modifications du code existant. C’est une solution idéale pour les équipes qui construisent des agents IA, des outils et des backends pilotés par LLM, et qui souhaitent une observabilité de niveau production sans dépendance forte à un fournisseur.

Fonctionnalités clés

• Traçage en temps réel pour les serveurs MCP
  Suivez en temps réel chaque appel d’outil, accès à une ressource et exécution liée à un prompt. Heimdall fournit des traces détaillées indiquant quand un outil a été invoqué, combien de temps il a pris, quels paramètres ont été passés et si l’exécution a réussi ou échoué.

• Analyses et visualisations via tableau de bord
  Utilisez le tableau de bord frontend intégré pour analyser la latence, les taux d’erreur et les schémas d’utilisation de vos services d’IA. Identifiez rapidement les outils lents, les endpoints défaillants ou les pics d’usage inhabituels.

• Architecture native OpenTelemetry
  Heimdall utilise OTLP/HTTP comme protocole d’ingestion et est entièrement aligné sur les standards OpenTelemetry. Cela facilite l’intégration avec vos stacks d’observabilité existants ou l’extension de votre pipeline de télémétrie.

• Intégration simple des SDK pour Python et JavaScript/TypeScript
  Heimdall fournit un SDK Python officiel (hmdl) et un SDK JavaScript/TypeScript (hmdl) avec des décorateurs/enveloppeurs simples :

  • Python : décorateur @trace_mcp_tool() pour tracer les outils MCP.
  • JS/TS : enveloppeur traceMCPTool() pour les fonctions d’outils asynchrones.

• Capture automatique des paramètres
  Le SDK Python inspecte automatiquement les signatures de fonctions afin de capturer les paramètres sous forme d’objets nommés (par ex. { "query": "test", "limit": 5 }). Le SDK JS/TS vous permet de définir paramNames pour obtenir le même résultat, rendant les traces plus lisibles et plus utiles pour le débogage.

• Déploiement auto‑hébergé
  Heimdall prend actuellement uniquement en charge un déploiement auto‑hébergé, vous offrant un contrôle complet sur l’infrastructure, la sécurité et la localisation des données. Vous exécutez le backend et le frontend sur vos propres serveurs ou dans votre environnement de développement local.

• Modèle organisation / projet
  Heimdall repose sur une structure Organisation → Projet :

  • Les organisations regroupent les projets et équipes associés.
  • Les projets représentent des applications ou environnements individuels, chacun avec un ID de projet unique pour la collecte des traces.

• Configuration basée sur les variables d’environnement
  Configurez les SDK Heimdall via des variables d’environnement (par ex. HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME, HEIMDALL_ENVIRONMENT, HEIMDALL_ENABLED) afin de simplifier les déploiements sur les environnements de développement, recette et production.

• Feuille de route (fonctionnalités prévues)
  Le dépôt décrit plusieurs fonctionnalités à venir :

  • Suivi des utilisateurs : associer les traces aux identités des utilisateurs pour une analyse au niveau utilisateur (actuellement toutes les requêtes sont anonymes).
  • Évaluation de LLM : système intégré de scoring de la qualité des modèles et workflows d’évaluation humaine.
  • Hébergement cloud managé : déploiement cloud géré optionnel pour les équipes qui préfèrent ne pas auto‑héberger.

Comment utiliser Heimdall

L’utilisation de Heimdall se fait en trois grandes étapes : lancer la plateforme, créer une organisation et un projet, puis intégrer les SDK dans vos serveurs MCP ou applications d’IA.

1. Préparer les prérequis

Assurez-vous de disposer des dépendances runtime nécessaires :

• Node.js 18+ (pour le backend et le frontend Heimdall)
• Python 3.9+ (si vous prévoyez d’utiliser le SDK Python)

Clonez le dépôt Heimdall depuis GitHub puis placez‑vous dans ce répertoire.

2. Démarrer le backend

Depuis la racine du projet :

cd backend
npm install
npm run dev

Cela démarre le backend Heimdall, qui expose un endpoint OTLP/HTTP (par défaut : http://localhost:4318) pour l’ingestion des traces.

3. Démarrer le frontend

Dans un autre terminal :

cd frontend
npm install
npm run dev

Le frontend est généralement accessible à l’adresse http://localhost:5173 et fournit l’interface web pour les organisations, projets et analyses.

4. Créer un compte, une organisation et un projet

1. Ouvrez http://localhost:5173 dans un navigateur.
2. Créez un compte avec votre adresse e‑mail et un mot de passe.
3. Créez une Organisation pour regrouper vos projets.
4. Créez un Projet au sein de l’organisation. Chaque projet obtient un ID de projet unique utilisé pour associer les traces entrantes.

Rendez‑vous ensuite sur la page Settings de votre projet pour trouver :

• Organization ID
• Project ID

Vous utiliserez ces valeurs dans la configuration de vos SDK.

5. Intégrer le SDK Python

Installez le package Python :

pip install hmdl

Exemple d’intégration de base :

from hmdl import HeimdallClient, trace_mcp_tool

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

Le décorateur crée automatiquement des traces pour chaque appel à search_tool, en capturant les arguments et les métadonnées d’exécution.

6. Intégrer le SDK JavaScript/TypeScript

Installez le package JS/TS :

npm install hmdl

Exemple d’intégration de base (style TypeScript) :

import { HeimdallClient, traceMCPTool } from 'hmdl';

const client = new HeimdallClient({
  endpoint: "http://localhost:4318",
  orgId: "your-org-id",       // Depuis Settings
  projectId: "your-project-id", // Depuis 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. Configuration via variables d’environnement (optionnel)

Vous pouvez configurer le client Heimdall à l’aide de variables d’environnement plutôt qu’en codant les valeurs en dur :

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"

Initialisez ensuite le client sans arguments :

# Python
from hmdl import HeimdallClient
client = HeimdallClient()

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

Une fois intégré, vos outils MCP émettront de la télémétrie vers le backend Heimdall, et vous pourrez analyser les traces et métriques dans l’interface web.

Cas d’usage

1. Observabilité pour agents IA et toolchains

Les équipes qui construisent des agents IA complexes reposant sur des outils MCP doivent comprendre comment chaque outil se comporte en conditions réelles. Heimdall fournit :

• Un suivi de la latence et une surveillance des erreurs par outil.
• Une visibilité sur les outils les plus fréquemment utilisés.
• Des insights sur la manière dont les prompts et ressources sont accédés via ces outils.

Cela aide les équipes à optimiser leur toolchain, à retirer les outils sous‑utilisés et à déboguer plus efficacement le comportement des agents.

2. Supervision en production des backends pilotés par LLM

Pour les organisations qui exploitent en production des API basées sur des LLM ou des microservices d’IA, Heimdall joue le rôle d’une couche d’observabilité essentielle :

• Surveiller le débit des requêtes et les temps de réponse.
• Identifier précisément les chemins lents causés par des dépendances externes ou des outils spécifiques.
• Détecter les pics d’erreurs ou les régressions après les déploiements.

Avec Heimdall intégré via OpenTelemetry, vous pouvez aligner l’observabilité de vos systèmes IA avec votre stack de supervision global.

3. Développement et débogage de serveurs MCP

Pendant le développement, Heimdall aide les ingénieurs à déboguer de nouveaux serveurs MCP ou outils :

• Tracer chaque appel à un nouvel outil lors des tests.
• Inspecter les paramètres et les données retournées pour vérifier la conformité fonctionnelle.
• Visualiser rapidement où des exceptions sont levées et dans quelles conditions.

Cela accélère les boucles de feedback et réduit le temps nécessaire pour identifier les problèmes dans des workflows multi‑outils et multi‑étapes.

4. Équipes internes plateforme et infrastructure IA

Les équipes plateforme qui fournissent une infrastructure IA interne à plusieurs équipes produit peuvent utiliser Heimdall pour offrir une observabilité standardisée :

• Créer des projets séparés pour chaque application ou client (tenant).
• Surveiller les schémas d’utilisation et de performance à l’échelle de l’organisation.
• Utiliser à terme le suivi par utilisateur (prévu) pour comprendre la consommation par équipe ou client.

Cela permet une meilleure planification de capacité, des modèles de refacturation/showback et une meilleure fiabilité de service.

5. Environnements sensibles à la confidentialité ou réglementés

Comme Heimdall est auto‑hébergé et open source, il convient particulièrement aux organisations opérant dans des environnements très réglementés ou à forte exigence de sécurité :

• Conserver toutes les traces et métadonnées au sein de votre propre infrastructure.
• Aligner les déploiements sur vos exigences internes de sécurité et de conformité.
• Personnaliser la plateforme ou l’intégrer à vos outils existants de supervision et d’alerte.

FAQ

Heimdall est‑il gratuit ?

Oui. Heimdall est publié sous licence MIT, ce qui le rend gratuit et open source pour un usage personnel comme commercial. Vous êtes responsable de l’hébergement et de l’exécution de la plateforme sur votre propre infrastructure. La feuille de route mentionne également une possible offre cloud managée à l’avenir, mais le projet principal reste open source.

Quelles technologies et standards Heimdall utilise‑t‑il ?

Heimdall est construit sur OpenTelemetry et utilise le protocole OTLP/HTTP (port par défaut 4318) pour l’ingestion des données de télémétrie. Le backend et le frontend sont des services basés sur Node.js, et des SDK clients officiels sont disponibles pour Python et JavaScript/TypeScript.

Quels environnements et langages sont pris en charge ?

Heimdall fournit actuellement des SDK officiels pour :

• Python (via le package hmdl ; nécessite Python 3.9+)
• JavaScript/TypeScript (via le package npm hmdl ; fonctionne avec Node.js 18+)

Comme Heimdall parle OpenTelemetry/OTLP, vous pouvez potentiellement intégrer d’autres langages à l’aide des bibliothèques OpenTelemetry standard, même si l’expérience la plus fluide reste avec les SDK officiels axés MCP.

Dois‑je forcément auto‑héberger Heimdall ?

Oui, à ce jour Heimdall est conçu comme une plateforme auto‑hébergée. Vous exécutez vous‑même les services backend et frontend (par ex. sur des machines locales, des VM, Kubernetes ou votre fournisseur d’hébergement préféré). La feuille de route mentionne un hébergement cloud managé comme amélioration future, mais ce n’est pas inclus dans la version actuelle.

Comment configurer plusieurs environnements (dev, staging, production) ?

Heimdall gère la configuration par environnement via des paramètres SDK et des variables d’environnement. Un schéma courant consiste à :

• Utiliser des Projets (et éventuellement des Organisations) distincts pour chaque environnement.
• Définir des variables d’environnement telles que HEIMDALL_ENDPOINT, HEIMDALL_ORG_ID, HEIMDALL_PROJECT_ID, HEIMDALL_SERVICE_NAME et HEIMDALL_ENVIRONMENT séparément dans chaque environnement.

Cela permet de garder les traces logiquement séparées et de comparer facilement les comportements entre développement, staging et production.

Heimdall peut‑il associer les traces à des utilisateurs finaux spécifiques ?

Le suivi au niveau utilisateur est indiqué comme une fonctionnalité TODO / en feuille de route. Actuellement, toutes les requêtes sont traitées comme anonymes et les identités des utilisateurs ne sont pas associées aux traces par défaut. Le projet prévoit d’ajouter le support du suivi utilisateur et de l’analytique par utilisateur dans de futures versions.