# Observability mit Langfuse

Jede Generation als Trace in Ihr Langfuse-Projekt senden, mit Modell, Tokens, Kosten in USD, Nutzer, Sitzung und Metadaten, ohne eigenes Mapping.

## Langfuse-Ziel einrichten

1. In Langfuse in den Projekteinstellungen ein API-Schlüsselpaar anlegen (`pk-lf-…`, `sk-lf-…`).
2. In den [Observability-Einstellungen](https://tokenlane.de/settings/observability) **Langfuse** als Zielart, die Region und beide Schlüssel wählen, speichern und einen Test-Trace senden. Der Test erscheint in Langfuse als **Tokenlane connection test**.
3. Den Export einschalten. Ab dann werden neue Nutzungsbelege zugestellt; ältere Belege werden nicht gesendet.

Tokenlane bildet URL (`/api/public/otel/v1/traces`), Basic-Zugang und Ingestion-Header selbst. Der Secret Key wird verschlüsselt gespeichert, nie wieder angezeigt und nie auditiert.

- **EU** (`cloud.langfuse.com`) ist die Voreinstellung. **US** (`us.cloud.langfuse.com`) verarbeitet Ihre Daten außerhalb der EU.
- **Selbst betriebenes** Langfuse braucht eine öffentliche HTTPS-Basis-URL; private und lokale Adressen werden abgelehnt.

## Was in Langfuse erscheint

Jede Generation ist eine Observation vom Typ `generation` (`embedding` bei Embeddings, sonst `span`) mit:

- Modell (`langfuse.observation.model.name`), Eingabe-, Ausgabe-, Cache- und Reasoning-Tokens aus den OpenTelemetry-GenAI-Attributen
- Zeit bis zum ersten Token bei Streaming (`langfuse.observation.completion_start_time`)
- Stufe `ERROR` mit dem Fehlertyp als Statusmeldung bei fehlgeschlagenen Requests, `WARNING` bei abgebrochenen
- Trace-Name aus Ihrem `trace.trace_name`, sonst Operation und Modell
- Nutzer (`user`), Sitzung (`session_id`), Tags aus `trace.tags`, wenn das eine Liste von Texten ist, Ihre Metadaten als filterbare `langfuse.trace.metadata.<key>` und die Umgebung aus `metadata.environment`

Prompts und Antworten erscheinen nur mit dem eingewilligten Inhaltsexport; siehe [Datenschutz und Compliance](https://tokenlane.de/docs/guides/privacy-and-compliance.md?lang=de).

## Kosten in USD

Langfuse speichert und zeigt Kosten nur in USD. Tokenlane rechnet den EUR-Betrag jeder Generation zum öffentlichen EZB-Referenzkurs um, der mit dem Beleg gespeichert ist, und sendet ihn als `langfuse.observation.cost_details` (`total`). Der interne Kurs für die Abrechnung in anderen Währungen wird nie gesendet. Die Metadaten der Observation tragen immer den EUR-Betrag (`cost_eur`) und mit Kurs zusätzlich `fx_usd_per_eur`, `fx_version` und `fx_as_of`.

Ohne EZB-Kurs für den Request oder bei unbekannten Kosten werden keine USD-Kosten gesendet, nur die EUR-Metadaten bleiben. Langfuse schätzt dann eventuell aus eigenen Modelldefinitionen. Um das abzuschalten, in Langfuse eine Modelldefinition anlegen, die auf Ihre Modellnamen passt und den Preis 0 hat.

## An Trace des Aufrufers anhängen

Langfuse-Ziele starten mit ausgeschaltetem **An Trace des Aufrufers anhängen**: Jede Generation ist die Wurzel ihres eigenen Traces und Langfuse zeigt sie vollständig. Schalten Sie es nur ein, wenn Ihre Anwendung eigene OpenTelemetry-Spans an dasselbe Langfuse-Projekt sendet; dann macht ein gültiger W3C-`traceparent` die Generation zum Kind Ihres Spans.
