Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Entdecken: Suche und Inspektion von Produktions-Traces

Lektion 12 von 16 Aktualisiert am 2. November 2026 Fortgeschritten
Auf dieser Seite
  1. Der Explorer: Ihr Fenster in die Produktion
  2. Senden von Traces
  3. Was ein Trace enthält
  4. Die Suchsprache
  5. Abfragen von Traces über das SDK
  6. Hinzufügen von Spans zu einem Datensatz
  7. Kernaussagen

Lektion am 2. November 2026 überarbeitet basierend auf Mistrals Seiten Send traces und Explore traces sowie dem mistralai SDK 3.7.0: Der Explorer konzentriert sich auf OpenTelemetry-Traces, die über eine Suchausdrucks-Sprache abgefragt werden; die veraltete Methode chat_completion_events.search existiert 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:

FeldInhalt
Trace IDKennung für die gesamte Ausführungskette
SpansOperationen: Modellaufrufe, Toolaufrufe, Workflow-Schritte
DauerZeit für jeden Span und den gesamten Trace
TokensEingabe- und Ausgabetokens für jeden Modellaufruf
StatusErfolg oder Fehler, einschließlich der Fehlermeldung
QuelleUrsprungsprodukt: SDK, Workflows, Vibe Work
TagsVom 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.

KategorieOperatorenBeispiel
Vergleich=, !=, <, <=, >, >=duration_ns > 5000000000
MusterLIKE, ILIKE, NOT LIKEservice_name LIKE '%agent%'
TeilstringCONTAINS, NOT CONTAINSservice_name CONTAINS 'sdk'
Regulärer AusdruckREGEXP, NOT REGEXPservice_name REGEXP '^my-'
BereichBETWEEN ... AND ...duration_ns BETWEEN 1000000 AND 5000000000
ListeIN (...), NOT IN (...)status_code IN ('Error', 'Ok')
VorhandenseinEXISTS, NOT EXISTSerror_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=true fü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