Héberger Langfuse sur un VPS : observabilité LLM sans SaaS

Les outils d'APM traditionnels (Datadog, New Relic) capturent la latence HTTP et les taux d'erreur, mais ils sont aveugles à ce qui se passe à l'intérieur d'un appel LLM. Une réponse qui arrive en 800 ms peut malgré tout être factuellement fausse, vague au point d'être inutile, ou trois fois plus coûteuse que celle de la veille parce qu'une régression de prompt est passée entre les mailles de la revue de code. Langfuse résout ce problème en traitant chaque interaction LLM comme une trace structurée : il enregistre le prompt complet (y compris le message système et l'historique de conversation), la complétion, le modèle utilisé, le décompte de tokens, la ventilation de la latence par span, ainsi que tous les scores d'évaluation que votre équipe y attache. Vous pouvez ensuite filtrer, comparer et reproduire n'importe quelle trace, individuellement ou de façon agrégée.

Langfuse v3 se présente comme une stack Docker Compose à six services : langfuse (frontend Next.js + API), langfuse-worker (tâches d'arrière-plan et évaluations), postgres (état de l'application), clickhouse (analytique des traces — stockage en colonnes optimisé pour les séries temporelles à forte cardinalité), redis (file d'attente et cache) et minio (stockage d'objets compatible S3 pour les pièces jointes média). ClickHouse justifie le minimum de 4 Go : son compilateur JIT et son moteur d'exécution vectorielle ont besoin de marge. Sur un VPS peu sollicité, la stack complète tourne au repos autour de 1,5–2 Go ; sous une charge de production modérée, prévoyez 4 Go, et 8 Go pour un traçage soutenu à haut débit. Les six services démarrent d'un seul docker compose up -d et sont gérés par AWX dans le flux en un clic de ServOrbit.

L'installation Marketplace de ServOrbit configure nginx et le certificat TLS pour vous. Si vous partez d'une installation manuelle, voici les points critiques.

Reverse proxy nginx. Langfuse écoute sur le port 3000. Votre vhost nginx doit proxifier ce port et transmettre les en-têtes nécessaires à NextAuth :

server {
    listen 443 ssl;
    server_name votre-domaine.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Si X-Forwarded-Proto n'est pas transmis, NextAuth génère des URLs de callback en http:// et les cookies de session ne s'attachent pas sur la réponse HTTPS — symptôme : boucle de redirection après la connexion.

Variables d'environnement clés. Le fichier .env de la stack Langfuse porte trois variables à personnaliser impérativement avant le premier démarrage :

- NEXTAUTH_SECRET : chaîne aléatoire longue (32 caractères minimum). Sans elle, les sessions ne persistent pas entre redémarrages.
- NEXTAUTH_URL : URL publique complète de votre instance (https://votre-domaine.com). Doit correspondre exactement au domaine nginx.
- LANGFUSE_INIT_ORG_ID, LANGFUSE_INIT_PROJECT_ID, LANGFUSE_INIT_PROJECT_PUBLIC_KEY, LANGFUSE_INIT_PROJECT_SECRET_KEY : optionnels, mais utiles pour provisionner une organisation et un projet au premier démarrage sans passer par l'interface.

TLS. Le déploiement ServOrbit utilise Let's Encrypt via certbot en mode DNS-01 — aucun port 80 à ouvrir. Si vous configurez le certificat manuellement, pointez les directives ssl_certificate et ssl_certificate_key vers les fichiers émis par certbot et activez le renouvellement automatique (certbot renew --quiet en cron).

Langfuse propose deux SDK officiels couvrant les principaux frameworks d'agents.

Python — décorateur @observe().
La façon la plus directe de tracer un agent :

from langfuse.decorators import observe, langfuse_context

@observe()
def run_agent(user_message: str) -> str:
    # chaque appel LLM imbriqué est automatiquement capturé
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": user_message}]
    )
    return response.choices[0].message.content

Toutes les fonctions imbriquées décorées avec @observe() apparaissent comme des spans enfants dans la même trace. Pour attacher des métadonnées (identifiant utilisateur, tags de session) :

langfuse_context.update_current_trace(
    user_id="user-42",
    session_id="session-abc",
    tags=["production", "agent-v2"]
)

LangChain. L'intégration native s'active en une ligne :

from langfuse.callback import CallbackHandler
handler = CallbackHandler()  # lit LANGFUSE_* depuis l'env
chain.invoke({"input": query}, config={"callbacks": [handler]})

Chaque nœud du graphe LangGraph (ou de la chaîne LangChain) devient un span avec son propre décompte de tokens et son coût.

TypeScript / JavaScript.
Initialisation du client :

import Langfuse from "langfuse";
const lf = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  baseUrl: process.env.LANGFUSE_HOST,
});

Création d'une trace et d'une génération :

const trace = lf.trace({ name: "agent-run", userId: "user-42" });
const generation = trace.generation({
  name: "llm-call",
  model: "gpt-4o",
  input: messages,
});
// … appel LLM …
generation.end({ output: result, usage: { input: 120, output: 45 } });
await lf.shutdownAsync(); // vider le buffer avant la fin du process

VercelAI SDK. Si vous utilisez le SDK VercelAI, l'intégration Langfuse s'active en ajoutant langfuseExporter comme SpanExporter dans la configuration OpenTelemetry — toutes les générations sont tracées sans modifier votre code métier.

Un problème actif affecte la vue Tracing v4 de Langfuse (signalé dans l'issue #16077, 17 commentaires en août 2026) : la colonne Cost ($) affiche systématiquement $0.00 pour toutes les traces.

La cause est structurelle. La vue v4 lit le coût porté par l'observation racine de chaque trace, qui est de type SPAN — un span n'a pas de coût propre, il ne fait qu'encapsuler des générations enfants. Le coût réel est distribué sur les observations de type GENERATION enfantes, mais la vue ne les agrège pas : elle lit la racine, trouve zéro, et affiche zéro.

Vos données sont intactes. Le coût est bien enregistré sur chaque génération ; seul l'affichage de la vue principale est faux. Trois contournements fonctionnent en attendant le correctif officiel :

1. Onglet Analytics / Metrics — la vue agrégée calcule les coûts sur l'ensemble des générations, pas sur la racine. C'est la source fiable pour suivre votre consommation quotidienne ou par modèle.

2. Filtrer par type GENERATION dans Traces — ajoutez le filtre observation_type = GENERATION dans la vue Traces. Vous ne voyez plus les traces parentes, mais chaque ligne affiche son coût réel.

3. Ouvrir le détail d'une trace — le panneau latéral affiche la ventilation complète par span et génération, avec les coûts corrects. Utile pour diagnostiquer une trace précise.

Si vous observez ce comportement sur votre instance, vérifiez que vous êtes bien sur Langfuse v3.x avec Tracing v4 activé. L'issue est ouverte et suivie par l'équipe Langfuse.

1. Le container langfuse ne démarre pas — Error: NEXTAUTH_SECRET manquant.
Langfuse v3 refuse de démarrer sans cette variable. Vérifiez votre .env :

docker compose config | grep NEXTAUTH_SECRET

Si la ligne est absente ou vide, générez une valeur et redémarrez :

openssl rand -base64 32
# collez le résultat dans .env : NEXTAUTH_SECRET=<valeur>
docker compose up -d langfuse

2. Connexion à la base de données refusée — ECONNREFUSED postgres:5432.
C'est presque toujours un problème de timing au démarrage : langfuse tente de se connecter avant que postgres soit prêt à accepter des connexions. Vérifiez que votre docker-compose.yml déclare depends_on avec condition: service_healthy pour le service postgres. Si le problème persiste, inspectez les logs postgres :

docker compose logs postgres --tail=50

3. Les traces n'arrivent pas dans le tableau de bord.
Vérifiez dans cet ordre : (a) les variables d'environnement LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY et LANGFUSE_SECRET_KEY sont-elles définies dans votre application ? (b) Le host pointe-t-il vers l'URL HTTPS publique et non vers localhost:3000 ? (c) Le SDK Python vide-t-il son buffer avant la fin du process (langfuse.flush() ou langfuse.shutdown()) ?

Un appel de test rapide depuis Python :

from langfuse import Langfuse
lf = Langfuse()
lf.trace(name="test-connection")
lf.flush()
print("Trace envoyée — vérifiez le dashboard.")

4. Boucle de redirection après la connexion.
Cause la plus fréquente : NEXTAUTH_URL ne correspond pas au domaine réellement utilisé, ou l'en-tête X-Forwarded-Proto n'est pas transmis par nginx. Vérifiez que NEXTAUTH_URL=https://votre-domaine.com (sans barre oblique finale) et que votre configuration nginx inclut proxy_set_header X-Forwarded-Proto $scheme;.

5. ClickHouse consomme toute la RAM.
Sous forte charge, ClickHouse peut dépasser son allocation initiale. Limitez sa consommation mémoire en ajoutant dans votre .env :

CLICKHOUSE_MAX_MEMORY_USAGE=2000000000

Cette valeur (2 Go) est un point de départ raisonnable pour un VPS de 8 Go hébergeant uniquement Langfuse. Ajustez selon le volume de traces.

Langsmith (le produit hébergé de LangChain) et Helicone sont les principales alternatives SaaS. Les deux sont excellents — et tous deux vous imposent de faire transiter vos traces par leurs serveurs. Pour les équipes qui manipulent des prompts sensibles (juridiques, financiers, médicaux), ou pour les environnements de conformité qui interdisent toute sortie de données vers un tiers, l'auto-hébergement n'est pas une option. Langfuse vous offre le même ensemble de fonctionnalités (traçage, évaluations, gestion des prompts, analytique des coûts) sur une infrastructure que vous maîtrisez. La licence MIT signifie aussi que vous pouvez lire, modifier et auditer chaque ligne du code par lequel transitent vos traces.