Verkennen: Productietraces doorzoeken en inspecteren
Op deze pagina
Les herschreven op 2 november 2026 op basis van de pagina’s Send traces en Explore traces van Mistral en de
mistralaiSDK 3.7.0: De Explorer richt zich op OpenTelemetry-traces die worden opgevraagd via een zoektaal voor expressies; de verouderde methodechat_completion_events.searchbestaat niet meer. Bronnen: Send traces · Explore traces.
De Explorer: Uw venster op de productie
De Trace Explorer is de plek waar u elke trace doorzoekt, filtert en inspecteert die door uw AI-toepassingen stroomt. U vindt deze in Studio onder Observability → Traces. Traces verschijnen hier echter pas nadat u ze hebt ingeschakeld: tracing staat standaard uit.
Traces verzenden
Met de Python SDK installeert u eerst de telemetry-extensie (mistralai[telemetry], versie 2.4.13 of hoger) en schakelt u deze vervolgens in op de client:
from mistralai.client import Mistral
from mistralai.extra.observability import configure_telemetry
client = Mistral(api_key="your-api-key")
configure_telemetry(client)
Vanaf dat moment traceert de SDK automatisch modelaanroepen, embeddings, agentbewerkingen, FIM-completions en OCR. Aanroepen van uw eigen tools worden niet standaard getraceerd: u moet hun spans toevoegen met behulp van de tracer van de SDK.
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 bronnen gedragen zich anders: Workflows traceren elke uitvoering zodra OTEL_ENABLED=true is ingesteld op de service, terwijl Vibe Work wordt geactiveerd via een admin-instelling in Studio. De TypeScript SDK biedt configureTelemetry. Vibe Code (CLI en Web) en de Studio Playground verzenden daarentegen geen traces. Alle bronnen maskeren standaard een deel van de gegevens voordat ze worden geëxporteerd; de pagina Data redaction licht dit beleid toe en legt uit hoe u dit kunt aanpassen.
Wat een trace bevat
Een trace is een boomstructuur van spans, waarbij elke span een bewerking in de keten vertegenwoordigt:
| Veld | Inhoud |
|---|---|
| Trace ID | Identificatie voor de volledige uitvoeringsketen |
| Spans | Bewerkingen: modelaanroepen, tool-aanroepen, workflowstappen |
| Duration | Tijd voor elke span en de volledige trace |
| Tokens | Input- en outputtokens voor elke modelaanroep |
| Status | Succes of fout, inclusief het foutbericht |
| Source | Bronproduct: SDK, Workflows, Vibe Work |
| Tags | Labels toegepast door de SDK en automatische metadata, zoals het model |
Als u op een trace klikt, opent de span-boom; elke span klapt uit om input, output, latentie en tokens weer te geven.
De zoektaal
De Explorer accepteert een expressietaal: voorwaarden op trace-velden gecombineerd met AND, OR en NOT.
| Categorie | Operators | Voorbeeld |
|---|---|---|
| Vergelijking | =, !=, <, <=, >, >= | duration_ns > 5000000000 |
| Patroon | LIKE, ILIKE, NOT LIKE | service_name LIKE '%agent%' |
| Substring | CONTAINS, NOT CONTAINS | service_name CONTAINS 'sdk' |
| Reguliere expressie | REGEXP, NOT REGEXP | service_name REGEXP '^my-' |
| Bereik | BETWEEN ... AND ... | duration_ns BETWEEN 1000000 AND 5000000000 |
| Lijst | IN (...), NOT IN (...) | status_code IN ('Error', 'Ok') |
| Aanwezigheid | EXISTS, NOT EXISTS | error_message EXISTS |
Beschikbare velden zijn onder meer service_name, status_code (Ok of Error), duration_ns (in nanoseconden), error_message, start_time, models_used (een lijst) en elk span-attribuut met haakjessyntax: span_attributes['gen_ai.request.model']. Voor lijsten vullen has(models_used, 'mistral-medium-latest'), hasany(...) en hasall(...) de functie CONTAINS aan.
# Alle mislukte traces van een service
service_name = 'agent-support' AND status_code = 'Error'
# Traces langer dan 5 seconden
duration_ns > 5000000000
# Traces die een specifiek model hebben aangeroepen
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'
Als een zoekopdracht geen resultaten oplevert, verwijdert u alle voorwaarden behalve het tijdsbereik en voegt u ze vervolgens één voor één weer toe. Een veelgemaakte fout is filteren op status_code = 'Error' terwijl de meeste traces succesvol zijn.
Traces opvragen via de SDK
U kunt dezelfde zoekopdrachten programmatisch uitvoeren over een tijdsbereik:
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")
Het antwoord gebruikt cursor-gebaseerde paginatie. De API-referentie documenteert de eindpunten Traces en Spans (zoeken, enkele trace, mogelijke velden en waarden, spans van een trace).
Spans toevoegen aan een dataset
De Explorer dient ook als startpunt voor testdatasets. Vanuit een trace biedt het menu van een span de optie Add span to dataset; in de weergave Spans kunt u tot 500 tegelijk selecteren en elk span-veld toewijzen aan een recordveld. Deze functie heeft betrekking op offline evaluaties, voorbehouden aan Enterprise-organisaties (Les 15).
Belangrijkste punten
- Tracing staat standaard uit:
configure_telemetry(client)schakelt dit in voor de Python SDK,OTEL_ENABLED=truevoor Workflows - Modelaanroepen worden automatisch getraceerd; tool-aanroepen vereisen handmatige tracing met
get_telemetry_tracer - De Explorer filtert traces met een expressietaal (
service_name,status_code,duration_ns,span_attributes['…']) - De SDK biedt dezelfde zoekmogelijkheid:
client.beta.observability.traces.search(search_expression=...) - Interessante spans worden met één klik of in batches van 500 recordgegevens in een dataset