Trace-Analyse mit LangSmith und Langfuse
Traces lesen: langsame Tools, falsche Entscheidungen und Fehlermuster erkennen.
Trace-Analyse mit LangSmith und Langfuse ist eine kostenlose AI Agents-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des AI Agents-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der AI Agents-Kurs umfasst insgesamt 4 Lektionen.
Warum sollten Sie Ihren Agent nachverfolgen?
Agents führen pro Ausführung mehrere LLM-Aufrufe und Tool-Aufrufe durch. Ohne Tracing ist das Debugging ein Ratespiel. Tracing zeichnet jeden Schritt auf: Eingaben, Ausgaben, Token-Verbrauch, Latenz und Fehler – und liefert Ihnen ein vollständiges Bild jeder Ausführung.
LangSmith einrichten
LangSmith ist die Tracing-Plattform von Anthropic für LangChain. Aktivieren Sie sie, indem Sie zwei Umgebungsvariablen festlegen. Jeder LangChain-Aufruf wird automatisch nachverfolgt und in der LangSmith-Benutzeroberfläche angezeigt.
import os
from dotenv import load_dotenv
load_dotenv()
# LangSmith tracing configuration
os.environ['LANGCHAIN_TRACING_V2'] = 'true'
os.environ['LANGCHAIN_API_KEY'] = os.environ.get('LANGSMITH_API_KEY', 'ls__...')
os.environ['LANGCHAIN_PROJECT'] = 'my-agent-project'
# Now any LangChain code is automatically traced
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
llm = ChatOpenAI(model='gpt-4o-mini', api_key=os.environ.get('OPENAI_API_KEY', 'sk-...'))
# This call is traced automatically
response = llm.invoke([HumanMessage(content='What is 2+2?')])
print(response.content)
# Check trace at: https://smith.langchain.comAusführungsmetadaten hinzufügen
Fügen Sie Traces Tags und Metadaten hinzu, damit Sie in der LangSmith-Benutzeroberfläche filtern und suchen können. Das ist nützlich, um verschiedene Agent-Versionen, Benutzer-IDs oder Experimentbezeichnungen nachzuverfolgen.
import os
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from langsmith import traceable
os.environ['LANGCHAIN_TRACING_V2'] = 'true'
os.environ['LANGCHAIN_API_KEY'] = 'ls__your-key'
os.environ['LANGCHAIN_PROJECT'] = 'my-agent-project'
llm = ChatOpenAI(model='gpt-4o-mini', api_key='sk-...')
@traceable(name='my-agent-run', tags=['production', 'v2'], metadata={'user_id': '42'})
def run_agent(question: str) -> str:
response = llm.invoke(
[HumanMessage(content=question)],
config={
'run_name': f'agent-{question[:20]}',
'tags': ['production'],
'metadata': {'user_id': '42', 'version': 'v2.1'}
}
)
return response.content
result = run_agent('Explain LangChain tracing')
print(result)Traces in der LangSmith-Benutzeroberfläche anzeigen
Im LangSmith-Dashboard sehen Sie jede Ausführung mit ihrem vollständigen Trace-Baum. Jeder Knoten zeigt Eingaben, Ausgaben, Token-Anzahl, Latenz und gegebenenfalls Fehler. Sie können Ausführungen vergleichen und nach Tags oder Projekten filtern.
- Nach Fehlerstatus filtern, um fehlgeschlagene Ausführungen zu finden
- Nach Latenz sortieren, um langsame Schritte zu identifizieren
- Zwei Ausführungen nebeneinander vergleichen, um Regressionen zu debuggen
# Programmatically query LangSmith for run data
from langsmith import Client
client = Client(api_key='ls__your-key')
# List recent runs for a project
runs = list(client.list_runs(
project_name='my-agent-project',
execution_order=1, # Top-level runs only
error=True, # Only failed runs
limit=10
))
for run in runs:
print(f'Run: {run.name}')
print(f' Status: {run.status}')
print(f' Latency: {run.end_time - run.start_time if run.end_time else "running"}')
print(f' Error: {run.error}')
print()Langfuse für benutzerdefiniertes Tracing
Langfuse ist eine Open-Source-Alternative zu LangSmith. Es funktioniert mit jedem LLM-Framework und mit benutzerdefiniertem Code. Verwenden Sie das Langfuse-SDK, um Traces und Spans manuell zu erstellen.
from langfuse import Langfuse
lf = Langfuse(
public_key='pk-lf-...',
secret_key='sk-lf-...',
host='https://cloud.langfuse.com' # Or your self-hosted URL
)
# Create a trace
trace = lf.trace(
name='email-agent-run',
user_id='user-42',
metadata={'environment': 'production'}
)
# Create a span for entity extraction
span = trace.span(
name='entity-extraction',
input={'text': 'Meeting with Alice from Google tomorrow'}
)
# Simulate work
extracted = ['Alice', 'Google']
# End the span with output
span.end(output={'entities': extracted})
print('Trace created in Langfuse')
print(f'View at: https://cloud.langfuse.com/trace/{trace.id}')LLM-Aufrufe in Langfuse nachverfolgen
Erstellen Sie für jeden LLM-Aufruf einen generation-Span. Dadurch werden das verwendete Modell, der Prompt, die Vervollständigung und die Token-Anzahl erfasst – die wichtigsten Daten für die Kostenanalyse.
from langfuse import Langfuse
import openai
lf = Langfuse(public_key='pk-lf-...', secret_key='sk-lf-...')
client = openai.OpenAI(api_key='sk-...')
def traced_llm_call(trace, prompt: str, model: str = 'gpt-4o-mini') -> str:
generation = trace.generation(
name='llm-call',
model=model,
input=[{'role': 'user', 'content': prompt}]
)
response = client.chat.completions.create(
model=model,
messages=[{'role': 'user', 'content': prompt}]
)
content = response.choices[0].message.content
generation.end(
output=content,
usage={
'prompt_tokens': response.usage.prompt_tokens,
'completion_tokens': response.usage.completion_tokens,
'total_tokens': response.usage.total_tokens
}
)
return content
trace = lf.trace(name='test-trace')
result = traced_llm_call(trace, 'What is the capital of France?')
print('Result:', result)Ausführungen nach Fehler und Latenz filtern
Verwenden Sie den LangSmith-Client, um problematische Ausführungen programmgesteuert zu finden. Filtern Sie nach Fehlerstatus, einem Latenzgrenzwert oder bestimmten Tags, um Ihre Debugging-Bemühungen zu fokussieren.
from langsmith import Client
from datetime import datetime, timedelta
client = Client(api_key='ls__your-key')
def find_slow_runs(project: str, latency_threshold_ms: int = 10000):
runs = list(client.list_runs(
project_name=project,
execution_order=1,
start_time=datetime.utcnow() - timedelta(hours=24)
))
slow_runs = []
for run in runs:
if run.end_time and run.start_time:
duration_ms = (run.end_time - run.start_time).total_seconds() * 1000
if duration_ms > latency_threshold_ms:
slow_runs.append({
'id': str(run.id),
'name': run.name,
'duration_ms': round(duration_ms),
'tags': run.tags
})
slow_runs.sort(key=lambda x: x['duration_ms'], reverse=True)
return slow_runs
print('Find slow runs function defined')
print('Usage: find_slow_runs("my-agent-project", latency_threshold_ms=5000)')Ausführungen vergleichen
Mit LangSmith können Sie zwei Ausführungen in der Benutzeroberfläche vergleichen und sehen, was sich geändert hat. Programmgesteuert können Sie Ausgabewerte, Token-Verbrauch und Latenz der Ausführungen vergleichen, um nach Änderungen am Modell oder Prompt Regressionen zu erkennen.
from langsmith import Client
client = Client(api_key='ls__your-key')
def compare_runs(run_id_1: str, run_id_2: str) -> dict:
run1 = client.read_run(run_id_1)
run2 = client.read_run(run_id_2)
def get_tokens(run):
if run.total_tokens:
return run.total_tokens
return 0
def get_latency_ms(run):
if run.end_time and run.start_time:
return (run.end_time - run.start_time).total_seconds() * 1000
return 0
return {
'run1': {'id': run_id_1, 'tokens': get_tokens(run1), 'latency_ms': get_latency_ms(run1), 'status': run1.status},
'run2': {'id': run_id_2, 'tokens': get_tokens(run2), 'latency_ms': get_latency_ms(run2), 'status': run2.status},
'token_delta': get_tokens(run2) - get_tokens(run1),
'latency_delta_ms': get_latency_ms(run2) - get_latency_ms(run1)
}
print('Run comparison function defined')Bewertungen und Feedback hinzufügen
Nachdem Sie eine Agent-Ausführung manuell oder automatisch bewertet haben, fügen Sie dem Trace eine Bewertung oder Feedback hinzu. Dadurch entsteht ein Datensatz zum Fine-Tuning oder zur Bewertung von Prompt-Änderungen.
from langsmith import Client
client = Client(api_key='ls__your-key')
def score_run(run_id: str, score: float, reasoning: str = ''):
# score: 0.0 (bad) to 1.0 (perfect)
client.create_feedback(
run_id=run_id,
key='quality',
score=score,
comment=reasoning
)
def auto_evaluate_run(run_id: str, expected_output: str, actual_output: str) -> float:
# Simple heuristic: check if key terms from expected output are present
expected_terms = set(expected_output.lower().split())
actual_terms = set(actual_output.lower().split())
overlap = len(expected_terms & actual_terms) / max(len(expected_terms), 1)
score = min(1.0, overlap * 1.5) # Normalize
score_run(run_id, score, f'Term overlap: {overlap:.2f}')
return score
print('Scoring functions defined')
print('Example: score_run("run-id-abc", 0.85, "Good answer but missing one detail")')Strukturierter Trace-Kontext
Fügen Sie Traces aussagekräftigen Kontext hinzu: Sitzungs-ID, Benutzer-ID, Agent-Version und Feature-Flags. So können Sie Traces einfach segmentieren und die Leistung über verschiedene Konfigurationen hinweg vergleichen.
import os
from langsmith import traceable
from langchain_core.runnables import RunnableConfig
def build_trace_config(user_id: str, session_id: str, version: str) -> dict:
return {
'metadata': {
'user_id': user_id,
'session_id': session_id,
'agent_version': version,
'environment': os.environ.get('ENV', 'development')
},
'tags': [version, os.environ.get('ENV', 'development')],
'run_name': f'agent-{user_id[:8]}'
}
@traceable
def run_agent_with_context(question: str, user_id: str, session_id: str):
config = build_trace_config(user_id, session_id, 'v2.3')
# Pass config to any LangChain component
# llm.invoke([HumanMessage(content=question)], config=config)
print(f'Running agent for user {user_id}, session {session_id}')
return 'Answer here'
result = run_agent_with_context('Question', 'user-001', 'sess-xyz')
print(result)Alerts einrichten
Überwachen Sie den Zustand Ihres Agents, indem Sie Alerts in LangSmith oder Langfuse einrichten. Lösen Sie einen Alert aus, wenn die Fehlerrate einen Grenzwert überschreitet, die P99-Latenz stark ansteigt oder ein bestimmter Schritt wiederholt fehlschlägt.
from langsmith import Client
from datetime import datetime, timedelta
client = Client(api_key='ls__your-key')
def check_error_rate(project: str, window_minutes: int = 60, threshold: float = 0.05) -> dict:
runs = list(client.list_runs(
project_name=project,
execution_order=1,
start_time=datetime.utcnow() - timedelta(minutes=window_minutes)
))
if not runs:
return {'error_rate': 0.0, 'alert': False}
error_count = sum(1 for r in runs if r.status == 'error')
error_rate = error_count / len(runs)
if error_rate > threshold:
print(f'ALERT: Error rate {error_rate:.1%} exceeds threshold {threshold:.1%}')
# Send to Slack/PagerDuty here
return {
'total_runs': len(runs),
'error_count': error_count,
'error_rate': round(error_rate, 4),
'alert': error_rate > threshold
}
print('Error rate monitor defined')Wissenscheck: Tracing
Testen Sie Ihr Verständnis des Agent-Tracings mit LangSmith und Langfuse.
Zusammenfassung: Tracing
LangSmith und Langfuse sind sich ergänzende Tools: LangSmith ist eng in LangChain integriert und erfordert nur minimale Einrichtung, während Langfuse mit jedem Framework funktioniert und Ihnen mehr Kontrolle bietet. Beide erfassen Eingaben, Ausgaben, Token-Verbrauch, Latenz und Fehler für jeden Agent-Schritt. Verwenden Sie Filter, Bewertungen und Alerts, um die Qualität Ihres Agents in der Produktion zu gewährleisten.
Häufig gestellte Fragen
Ist die Lektion „Trace-Analyse mit LangSmith und Langfuse“ kostenlos?
Ja — der vollständige Text von „Trace-Analyse mit LangSmith und Langfuse“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des AI Agents-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der AI Agents-Kurs umfasst insgesamt 4 Lektionen.
Was lerne ich in „Trace-Analyse mit LangSmith und Langfuse“?
Traces lesen: langsame Tools, falsche Entscheidungen und Fehlermuster erkennen. Du übst AI Agents mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.
Brauche ich Erfahrung, um AI Agents zu starten?
Keine Vorkenntnisse erforderlich. AI Agents auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.
Wie lange dauert die Lektion „Trace-Analyse mit LangSmith und Langfuse“?
Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.
Kann ich in dieser AI Agents-Lektion Code schreiben und ausführen?
Ja. Jede AI Agents-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.
Alle Lektionen in diesem Kurs
- Trace-Analyse mit LangSmith und Langfuse
- Token- und Kostenprofiling pro Schritt
- Langsame und teure Schritte identifizieren
- Ursachenanalyse für Agentenfehler