Explore: Căutați și inspectați urmele de producție
Pe această pagină
Lecție rescrisă la 2 noiembrie 2026 pe baza paginilor Send traces și Explore traces de la Mistral și a SDK-ului
mistralai3.7.0: Explorerul se concentrează pe urmele OpenTelemetry interogate printr-un limbaj de expresii de căutare; metoda vechechat_completion_events.searchnu mai există. Surse: Send traces · Explore traces.
Explorerul: Fereastra dumneavoastră către producție
Trace Explorer este locul unde căutați, filtrați și inspectați fiecare urmă care circulă prin aplicațiile dumneavoastră de IA. Îl veți găsi în Studio sub Observability → Traces. Totuși, urmele nu vor apărea acolo decât dacă le activați mai întâi: urmărirea (tracing) este dezactivată implicit.
Trimiterea urmelor
Cu SDK-ul pentru Python, instalați extensia de telemetrie (mistralai[telemetry], versiunea 2.4.13 sau ulterioară), apoi activați-o pe client:
from mistralai.client import Mistral
from mistralai.extra.observability import configure_telemetry
client = Mistral(api_key="your-api-key")
configure_telemetry(client)
De acel moment, SDK-ul urmărește automat apelurile de modele, embedding-urile, operațiunile agenților, completările FIM și OCR. Apelurile către propriile dumneavoastră instrumente nu sunt urmărite implicit: trebuie să adăugați segmentele (spans) lor folosind tracer-ul SDK-ului.
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
Alte surse se comportă diferit: Workflows urmăresc fiecare execuție imediat ce OTEL_ENABLED=true este setat pe serviciu, în timp ce Vibe Work se activează printr-o setare de administrator în Studio. SDK-ul pentru TypeScript oferă configureTelemetry. În schimb, Vibe Code (CLI și Web) și Studio Playground nu trimit urme. Toate sursele redactează o parte din date implicit înainte de export; pagina Data redaction detaliază această politică și modul de ajustare a acesteia.
Ce conține o urmă
O urmă este un arbore de segmente (spans), unde fiecare segment reprezintă o operațiune din lanț:
| Câmp | Conținut |
|---|---|
| Trace ID | Identificator pentru întregul lanț de execuție |
| Spans | Operațiuni: apeluri de modele, apeluri de instrumente, pași de workflow |
| Duration | Timp pentru fiecare segment și pentru întreaga urmă |
| Tokens | Tokeni de intrare și ieșire pentru fiecare apel de model |
| Status | Succes sau eroare, inclusiv mesajul de eroare |
| Source | Produsul de origine: SDK, Workflows, Vibe Work |
| Tags | Etichete aplicate de SDK și metadate automate, cum ar fi modelul |
Făcând clic pe o urmă, se deschide arborele său de segmente; fiecare segment se extinde pentru a afișa intrarea, ieșirea, latența și tokenii.
Limbajul de căutare
Explorerul acceptă un limbaj de expresii: condiții asupra câmpurilor urmelor combinate cu AND, OR și NOT.
| Categorie | Operatori | Exemplu |
|---|---|---|
| Comparație | =, !=, <, <=, >, >= | duration_ns > 5000000000 |
| Model (Pattern) | LIKE, ILIKE, NOT LIKE | service_name LIKE '%agent%' |
| Subșir | CONTAINS, NOT CONTAINS | service_name CONTAINS 'sdk' |
| Expresie regulată | REGEXP, NOT REGEXP | service_name REGEXP '^my-' |
| Interval | BETWEEN ... AND ... | duration_ns BETWEEN 1000000 AND 5000000000 |
| Listă | IN (...), NOT IN (...) | status_code IN ('Error', 'Ok') |
| Prezență | EXISTS, NOT EXISTS | error_message EXISTS |
Câmpurile disponibile includ service_name, status_code (Ok sau Error), duration_ns (în nanosecunde), error_message, start_time, models_used (o listă) și orice atribut de segment folosind sintaxa cu paranteze pătrate: span_attributes['gen_ai.request.model']. Pentru liste, has(models_used, 'mistral-medium-latest'), hasany(...) și hasall(...) completează CONTAINS.
# Toate urmele eșuate de la un serviciu
service_name = 'agent-support' AND status_code = 'Error'
# Urme mai lungi de 5 secunde
duration_ns > 5000000000
# Urme care au apelat un model specific
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'
Dacă o căutare nu returnează rezultate, eliminați toate condițiile cu excepția intervalului de timp, apoi re-adăugați-le una câte una. O greșeală frecventă este filtrarea după status_code = 'Error' când majoritatea urmelor reușesc.
Interogarea urmelor prin SDK
Puteți efectua aceleași căutări programatic pe un interval de timp:
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")
Răspunsul folosește paginarea bazată pe cursor. Referința API documentează endpoint-urile Traces și Spans (căutare, urmă unică, câmpuri și valori posibile, segmente ale unei urme).
Adăugarea segmentelor într-un set de date
Explorerul servește, de asemenea, ca punct de plecare pentru seturile de date de test. Dintr-o urmă, meniul unui segment oferă opțiunea Add span to dataset; în vizualizarea Spans, puteți selecta până la 500 simultan și puteți mapa fiecare câmp de segment la un câmp de înregistrare. Această funcție se referă la evaluările offline, rezervate organizațiilor Enterprise (Lecția 15).
Puncte cheie
- Urmărirea este dezactivată implicit:
configure_telemetry(client)o activează pentru SDK-ul Python,OTEL_ENABLED=truepentru Workflows - Apelurile de modele sunt urmărite automat; apelurile de instrumente necesită urmărire manuală cu
get_telemetry_tracer - Explorerul filtrează urmele folosind un limbaj de expresii (
service_name,status_code,duration_ns,span_attributes['…']) - SDK-ul expune aceeași capacitate de căutare:
client.beta.observability.traces.search(search_expression=...) - Segmentele interesante devin înregistrări în setul de date într-un singur clic sau în loturi de 500