> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localmind.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Langfuse anbinden (OpenTelemetry)
> OTLP-Trace-Export an ein selbst betriebenes Langfuse anbinden — Einrichtung und Richtwerte.
Localmind exportiert Trace-Daten (Aufrufketten) über den offenen Standard OpenTelemetry (OTLP) — der Export ist eingebaut, damit binden Sie ein selbst betriebenes [Langfuse](https://langfuse.com) an. Die Anbindung besteht aus zwei Zeilen in `backend/.env` und einem Neustart des Backend-Containers.
```
Localmind-Backend --OTLP/HTTPS (443)--> Langfuse-Server --> Langfuse-Oberfläche
(Ihre Instanz) Traces, Push (Ihr Betrieb) (Tracing -> Traces)
```
Die eingebauten Ansichten für Nutzung und Systemzustand (Analytik, Audit-Logs, System-Info) sind unter [Observability](/administration/observability) beschrieben.
Das Grafana/Tempo/Loki-Szenario für Infrastruktur-Monitoring ist in der On-Premise-Deployment-Checkliste beschrieben, die Sie mit Ihren Installationsunterlagen erhalten. Parallel lassen sich beide Szenarien nur über einen OTel-Collector als Verteiler betreiben — stimmen Sie das mit Localmind ab.
## Voraussetzungen
| Voraussetzung | Details |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Langfuse läuft und ist erreichbar | Selbst betriebenes Langfuse (Docker), vom Localmind-Server per HTTPS erreichbar; Firewall Port 443 ausgehend. Server erst in Planung? Richtwerte unter [Dimensionierung](#dimensionierung-des-langfuse-servers-richtwerte) |
| Gültiges TLS-Zertifikat am Langfuse | Muss vom Localmind-Server als vertrauenswürdig erkannt werden; interne CA / selbstsigniert: vorher mit Localmind abstimmen |
| Langfuse-Projekt mit API-Schlüsseln | Public Key (`pk-lf-…`) und Secret Key (`sk-lf-…`) des Projekts |
| Zugriff auf den Localmind-Server | SSH mit sudo, Zugriff auf das Installationsverzeichnis (`backend/.env`) |
| Kurzes Wartungsfenster | Der Backend-Container wird einmal neu gestartet |
## Einrichtung
Legen Sie in der Langfuse-Oberfläche ein Projekt an (z. B. „Localmind Produktion"). Erstellen Sie im Projekt unter **Settings → API Keys → Create new API keys** ein Schlüsselpaar und notieren Sie beide Werte: Public Key (`pk-lf-…`) und Secret Key (`sk-lf-…`, wird nur einmal angezeigt).
Der OTLP-Empfangsendpunkt lautet:
```
https:///api/public/otel
```
Langfuse nimmt OTLP über HTTP (http/protobuf) an, nicht über gRPC.
Langfuse authentifiziert eingehende Traces per HTTP Basic Auth mit den Projekt-Schlüsseln. Erzeugen Sie den Base64-Wert aus `publickey:secretkey`:
```bash theme={null}
echo -n "pk-lf-XXXXXXXX:sk-lf-XXXXXXXX" | base64
```
Verwenden Sie `echo -n` — ohne `-n` gerät ein Zeilenumbruch in den Wert und die Authentifizierung schlägt fehl. Versenden Sie den Secret Key nicht per E-Mail oder Chat.
Ergänzen Sie in `backend/.env` im Installationsverzeichnis der Instanz zwei Zeilen (Werte ohne Anführungszeichen):
```ini backend/.env theme={null}
OTEL_EXPORTER_OTLP_ENDPOINT=https:///api/public/otel
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic
```
Binden Sie nur das Backend an — dort entstehen die Traces. Die Frontend-Variable `PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT` gehört zum Grafana-Szenario und bleibt leer.
Die Datei ist berechtigungsgeschützt (0600) — verändern Sie die Berechtigungen nicht.
```bash theme={null}
cd
docker compose restart backend
```
1. Führen Sie in Localmind einen kurzen Test-Chat mit einem Agenten.
2. Öffnen Sie in Langfuse das Projekt: **Tracing → Traces**, Zeitraum „letzte Stunde".
3. Neue Trace-Einträge erscheinen; der Export arbeitet gepuffert, die ersten Einträge können 1–2 Minuten verzögert sein.
Sie sehen die Aufrufketten des Backends (HTTP-, Datenbank-, Redis- und externe Aufrufe sowie KI-Aufrufe); die Detailtiefe der KI-spezifischen Attribute ist versionsabhängig.
## Fehlerbehebung
| Problem | Mögliche Ursache | Lösung |
| ----------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Keine Traces | Variable nicht gesetzt / Container nicht neu gestartet | `backend/.env` prüfen, `docker compose restart backend` |
| Keine Traces, Konfiguration korrekt | Firewall 443 ausgehend / Langfuse nicht erreichbar | Vom Localmind-Server: `curl -sS -o /dev/null -w '%{http_code}' https:///api/public/otel/v1/traces` — HTTP-Antwort (401/405) = erreichbar, Timeout = Firewall/DNS |
| Keine Traces, Endpunkt erreichbar | Export steht auf gRPC | In `backend/.env` zusätzlich `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`, Backend neu starten |
| 401 / unauthorized | Base64 fehlerhaft oder Keys aus anderem Projekt | Base64 neu erzeugen (mit `echo -n`); bleibt es bei 401: Leerzeichen als `%20` kodieren (`Authorization=Basic%20`) |
| TLS-Fehler im Backend-Log | Zertifikat nicht vertrauenswürdig (interne CA) | Gültige Kette am Langfuse hinterlegen oder mit Localmind abstimmen |
| Traces ohne KI-Details | Detailtiefe versionsabhängig | Wenden Sie sich an [support@localmind.ai](mailto:support@localmind.ai) |
| Disk läuft voll | Retention nicht konfiguriert | Aufbewahrungsdauer in Langfuse setzen, Dimensionierung nachkalibrieren |
## Dimensionierung des Langfuse-Servers (Richtwerte)
Ein selbst betriebenes Langfuse besteht aus vier Komponenten:
| Komponente | Aufgabe |
| ----------------- | --------------------------------- |
| Postgres | Transaktionale Daten |
| ClickHouse | Trace-Analytik |
| Redis/Valkey | Queue/Cache |
| S3-/Blob-Speicher | Rohdaten aller eingehenden Events |
Im Standard-Docker-Setup laufen alle vier auf einer VM; der Blob-Speicher ist der größte Speichertreiber.
Offizielle Anhaltspunkte:
* Langfuse veröffentlicht bewusst keine festen Sizing-Zahlen (Stand Juli 2026).
* Persistentes Volume ab 100 GB als Startwert.
* Kubernetes-Produktivsetups: Ressourcen-Preset „large", 3 Replicas.
* Postgres und ClickHouse zwingend in Zeitzone UTC.
Die folgenden Werte sind eine Modellrechnung — nach etwa 4 Wochen Realbetrieb am tatsächlichen Verbrauch nachkalibrieren.
```
Traces/Monat ≈ aktive Nutzer × KI-Anfragen je Nutzer und Arbeitstag × 21
Speicher/Monat ≈ Traces/Monat × Ø-Trace-Größe × 2 (Rohdaten im Blob + Kopie in ClickHouse)
```
Beispiel: 1.000 aktive Nutzer × 10 KI-Anfragen je Arbeitstag ≈ 210.000 Traces/Monat. Bei Ø 100 KB je Trace (Prompt, Antwort, RAG-Kontext, Metadaten) ≈ 40 GB/Monat; bei 12 Monaten Aufbewahrung ≈ 500 GB — mit Reserve also eine 1-TB-Disk.
| Aktive Nutzer | vCPU | RAM | SSD (12 Monate Retention) | Anmerkung |
| ------------- | ---- | ----- | ------------------------- | -------------------------------------------------------- |
| bis 250 | 4 | 16 GB | 250 GB | alles auf einer VM (Docker-Compose-Standard) |
| bis 1.000 | 8 | 32 GB | 1 TB | alles auf einer VM; Disk-Monitoring einrichten |
| bis 5.000 | 16 | 64 GB | 2–4 TB | ClickHouse ggf. eigener Node; Blob auf externes S3/MinIO |
Multimodale Inhalte (Bilder/Audio) erhöhen die Ø-Trace-Größe deutlich — wählen Sie dann die nächsthöhere Stufe.
Retention konfigurieren statt unbegrenzt sammeln — die Aufbewahrungsdauer ist der größte Hebel für den Speicherbedarf.