Entdecken: Suche und Inspektion von Produktions-Traces
Auf dieser Seite
Lektion am 2. November 2026 überarbeitet basierend auf Mistrals Seiten Send traces und Explore traces sowie dem
mistralaiSDK 3.7.0: Der Explorer konzentriert sich auf OpenTelemetry-Traces, die über eine Suchausdrucks-Sprache abgefragt werden; die veraltete Methodechat_completion_events.searchexistiert nicht mehr. Quellen: Send traces · Explore traces.
Der Explorer: Ihr Fenster in die Produktion
Der Trace Explorer ist der Ort, an dem Sie alle durch Ihre KI-Anwendungen fließenden Traces durchsuchen, filtern und inspizieren können. Sie finden ihn in Studio unter Observability → Traces. Traces erscheinen dort jedoch nicht, es sei denn, Sie aktivieren sie zuvor: Tracing ist standardmäßig deaktiviert.
Senden von Traces
Mit dem Python-SDK installieren Sie die Telemetrie-Erweiterung (mistralai[telemetry], Version 2.4.13 oder höher) und aktivieren sie anschließend am Client:
from mistralai.client import Mistral
from mistralai.extra.observability import configure_telemetry
client = Mistral(api_key="your-api-key")
configure_telemetry(client)
Ab diesem Zeitpunkt verfolgt das SDK automatisch Modellaufrufe, Embeddings, Agentenoperationen, FIM-Vervollständigungen und OCR. Aufrufe Ihrer eigenen Tools werden nicht standardmäßig verfolgt: Sie müssen deren Spans mithilfe des Tracers des SDK hinzufügen.
from mistralai.extra.observability import get_telemetry_tracer
tracer = get_telemetry_tracer(client, "agent-support")
with tracer.start_as_current_span("invoke_agent"):
response = client.chat.complete(
model="mistral-small-latest",
messages=[{"role": "user", "content": "What is the status of order 4521?"}],
)
with tracer.start_as_current_span("execute_tool order_tracking") as span_tool:
span_tool.set_attribute("gen_ai.tool.name", "order_tracking")
span_tool.set_attribute("gen_ai.tool.call.arguments", "4521")
# call your tool here
Andere Quellen verhalten sich unterschiedlich: Workflows verfolgen jede Ausführung, sobald OTEL_ENABLED=true auf dem Dienst gesetzt ist, während Vibe Work über eine Admin-Einstellung in Studio aktiviert wird. Das TypeScript-SDK bietet configureTelemetry. Im Gegensatz dazu senden Vibe Code (CLI und Web) sowie der Studio-Playground keine Traces. Alle Quellen redigieren standardmäßig einen Teil der Daten vor dem Export; die Seite Data redaction erläutert diese Richtlinie und zeigt, wie diese angepasst werden kann.
Was ein Trace enthält
Ein Trace ist ein Baum von Spans, wobei jeder Span eine Operation in der Kette darstellt:
| Feld | Inhalt |
|---|---|
| Trace ID | Kennung für die gesamte Ausführungskette |
| Spans | Operationen: Modellaufrufe, Toolaufrufe, Workflow-Schritte |
| Dauer | Zeit für jeden Span und den gesamten Trace |
| Tokens | Eingabe- und Ausgabetokens für jeden Modellaufruf |
| Status | Erfolg oder Fehler, einschließlich der Fehlermeldung |
| Quelle | Ursprungsprodukt: SDK, Workflows, Vibe Work |
| Tags | Vom SDK angewandte Labels und automatische Metadaten, wie das Modell |
Das Anklicken eines Traces öffnet dessen Span-Baum; jeder Span lässt sich erweitern, um Eingabe, Ausgabe, Latenz und Tokens anzuzeigen.
Die Suchsprache
Der Explorer akzeptiert eine Ausdrucks-Sprache: Bedingungen zu Trace-Feldern, kombiniert mit AND, OR und NOT.
| Kategorie | Operatoren | Beispiel |
|---|---|---|
| Vergleich | =, !=, <, <=, >, >= | duration_ns > 5000000000 |
| Muster | LIKE, ILIKE, NOT LIKE | service_name LIKE '%agent%' |
| Teilstring | CONTAINS, NOT CONTAINS | service_name CONTAINS 'sdk' |
| Regulärer Ausdruck | REGEXP, NOT REGEXP | service_name REGEXP '^my-' |
| Bereich | BETWEEN ... AND ... | duration_ns BETWEEN 1000000 AND 5000000000 |
| Liste | IN (...), NOT IN (...) | status_code IN ('Error', 'Ok') |
| Vorhandensein | EXISTS, NOT EXISTS | error_message EXISTS |
Verfügbare Felder umfassen service_name, status_code (Ok oder Error), duration_ns (in Nanosekunden), error_message, start_time, models_used (eine Liste) und jedes Span-Attribut unter Verwendung der Klammer-Syntax: span_attributes['gen_ai.request.model']. Für Listen ergänzen has(models_used, 'mistral-medium-latest'), hasany(...) und hasall(...) die Funktion CONTAINS.
# Alle fehlgeschlagenen Traces eines Dienstes
service_name = 'agent-support' AND status_code = 'Error'
# Traces länger als 5 Sekunden
duration_ns > 5000000000
# Traces, die ein bestimmtes Modell aufgerufen haben
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'
Wenn eine Suche keine Ergebnisse liefert, entfernen Sie alle Bedingungen außer dem Zeitbereich und fügen Sie sie dann einzeln wieder hinzu. Ein häufiger Fehler besteht darin, nach status_code = 'Error' zu filtern, wenn die meisten Traces erfolgreich sind.
Abfragen von Traces über das SDK
Sie können dieselben Suchen programmatisch über einen Zeitbereich durchführen:
from datetime import datetime, timedelta, timezone
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
now = datetime.now(timezone.utc)
response = client.beta.observability.traces.search(
from_=now - timedelta(days=1),
to=now,
search_expression="service_name = 'agent-support' AND status_code = 'Error'",
page_size=50,
)
for trace in response.traces.results or []:
print(f"{trace.trace_id} {trace.root_span_name} : {trace.duration_ns / 1e9:.1f} s")
Die Antwort verwendet eine Cursor-basierte Paginierung. Die API-Referenz dokumentiert die Endpunkte Traces und Spans (Suche, einzelner Trace, mögliche Felder und Werte, Spans eines Traces).
Hinzufügen von Spans zu einem Datensatz
Der Explorer dient auch als Ausgangspunkt für Testdatensätze. Über das Menü eines Spans in einem Trace können Sie Span zum Datensatz hinzufügen wählen; in der Ansicht Spans können Sie bis zu 500 Spans gleichzeitig auswählen und jedes Span-Feld einem Datensatzfeld zuordnen. Diese Funktion steht in Verbindung mit Offline-Bewertungen, die nur für Enterprise-Organisationen reserviert sind (Lektion 15).
Kernaussagen
- Tracing ist standardmäßig deaktiviert:
configure_telemetry(client)aktiviert es für das Python-SDK,OTEL_ENABLED=truefür Workflows - Modellaufrufe werden automatisch verfolgt; Toolaufrufe erfordern manuelles Tracing mit
get_telemetry_tracer - Der Explorer filtert Traces mit einer Ausdrucks-Sprache (
service_name,status_code,duration_ns,span_attributes['…']) - Das SDK stellt dieselbe Suchfähigkeit bereit:
client.beta.observability.traces.search(search_expression=...) - Interessante Spans werden mit einem Klick oder in Batches von 500 zu Datensatz-Records