Eksploracja: Wyszukiwanie i inspekcja śladów produkcyjnych
Na tej stronie
Lekcja przepisana 2 listopada 2026 na podstawie stron Mistral Send traces i Explore traces oraz SDK
mistralaiw wersji 3.7.0: Eksplorator koncentruje się na śladach OpenTelemetry queryowanych za pomocą języka wyrażeń wyszukiwania; przestarzała metodachat_completion_events.searchjuż nie istnieje. Źródła: Send traces · Explore traces.
Eksplorator: Twoje okno na produkcję
Eksplorator śladów (Trace Explorer) to miejsce, w którym wyszukujesz, filtrujesz i inspekujesz każdy ślad przepływający przez Twoje aplikacje AI. Znajdziesz go w Studio w sekcji Obserwowalność → Ślady. Pamiętaj jednak, że ślady się tam nie pojawią, dopóki ich nie włączysz: domyślnie tworzenie śladów jest wyłączone.
Wysyłanie śladów
Korzystając z Python SDK, zainstaluj rozszerzenie telemetryczne (mistralai[telemetry], wersja 2.4.13 lub nowsza), a następnie włącz je na kliencie:
from mistralai.client import Mistral
from mistralai.extra.observability import configure_telemetry
client = Mistral(api_key="your-api-key")
configure_telemetry(client)
Od tego momentu SDK automatycznie tworzy ślady wywołań modeli, osadzeń (embeddings), operacji agentów, uzupełnień FIM oraz OCR. Wywołania Twoich własnych narzędzi nie są śledzone domyślnie: musisz dodać ich spany, używając modułu śledzącego (tracer) z 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
Inne źródła zachowują się inaczej: Workflows śledzą każde wykonanie natychmiast po ustawieniu OTEL_ENABLED=true na usłudze, podczas gdy Vibe Work aktywuje się poprzez ustawienie administracyjne w Studio. TypeScript SDK udostępnia funkcję configureTelemetry. Z kolei Vibe Code (CLI i Web) oraz Studio Playground nie wysyłają śladów. Wszystkie źródła domyślnie anonimizują część danych przed eksportem; strona Data redaction szczegółowo opisuje tę politykę i sposób jej dostosowania.
Co zawiera ślad
Ślad to drzewo spanów, gdzie każdy span reprezentuje operację w łańcuchu:
| Pole | Zawartość |
|---|---|
| Trace ID | Identyfikator całego łańcucha wykonania |
| Spans | Operacje: wywołania modeli, wywołania narzędzi, kroki workflow |
| Duration | Czas trwania każdego spanu i całego śladu |
| Tokens | Tokeny wejściowe i wyjściowe dla każdego wywołania modelu |
| Status | Sukces lub błąd, w tym komunikat o błędzie |
| Source | Pochodzenie produktu: SDK, Workflows, Vibe Work |
| Tags | Etykiety nakładane przez SDK i automatyczne metadane, takie jak model |
Kliknięcie śladu otwiera jego drzewo spanów; każdy span rozwija się, pokazując dane wejściowe, wyjściowe, opóźnienie i liczbę tokenów.
Język wyszukiwania
Eksplorator akceptuje język wyrażeń: warunki dotyczące pól śladu połączone operatorami AND, OR i NOT.
| Kategoria | Operatory | Przykład |
|---|---|---|
| Porównanie | =, !=, <, <=, >, >= | duration_ns > 5000000000 |
| Wzorzec | LIKE, ILIKE, NOT LIKE | service_name LIKE '%agent%' |
| Podciąg | CONTAINS, NOT CONTAINS | service_name CONTAINS 'sdk' |
| Wyrażenie regularne | REGEXP, NOT REGEXP | service_name REGEXP '^my-' |
| Zakres | BETWEEN ... AND ... | duration_ns BETWEEN 1000000 AND 5000000000 |
| Lista | IN (...), NOT IN (...) | status_code IN ('Error', 'Ok') |
| Obecność | EXISTS, NOT EXISTS | error_message EXISTS |
Dostępne pola obejmują service_name, status_code (Ok lub Error), duration_ns (w nanosekundach), error_message, start_time, models_used (lista) oraz dowolny atrybut spanu używający składni z nawiasami: span_attributes['gen_ai.request.model']. Dla list funkcje has(models_used, 'mistral-medium-latest'), hasany(...) i hasall(...) uzupełniają operator CONTAINS.
# Wszystkie nieudane ślady z usługi
service_name = 'agent-support' AND status_code = 'Error'
# Ślady trwające dłużej niż 5 sekund
duration_ns > 5000000000
# Ślady, które wywołały określony model
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'
Jeśli wyszukiwanie nie zwraca wyników, usuń wszystkie warunki oprócz zakresu czasowego, a następnie dodawaj je po jednym. Częstym błędem jest filtrowanie po status_code = 'Error', gdy większość śladów kończy się sukcesem.
Queryowanie śladów przez SDK
Możesz wykonywać te same wyszukiwania programistycznie w określonym zakresie czasowym:
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")
Odpowiedź wykorzystuje paginację opartą na kursorach. Referencje API dokumentują punkty końcowe Traces i Spans (wyszukiwanie, pojedynczy ślad, możliwe pola i wartości, spany śladu).
Dodawanie spanów do zbioru danych
Eksplorator służy również jako punkt wyjścia do tworzenia zbiorów danych testowych. Ze spanu w menu śladu dostępna jest opcja Add span to dataset; w widoku Spans możesz wybrać jednocześnie do 500 elementów i zmapować każde pole spanu na pole rekordu. Funkcja ta dotyczy ewaluacji offline, zarezerwowanych dla organizacji Enterprise (Lekcja 15).
Kluczowe wnioski
- Tworzenie śladów jest domyślnie wyłączone:
configure_telemetry(client)włącza je dla Python SDK, aOTEL_ENABLED=truedla Workflows - Wywołania modeli są śledzone automatycznie; wywołania narzędzi wymagają ręcznego śledzenia za pomocą
get_telemetry_tracer - Eksplorator filtruje ślady przy użyciu języka wyrażeń (
service_name,status_code,duration_ns,span_attributes['…']) - SDK udostępnia tę samą możliwość wyszukiwania:
client.beta.observability.traces.search(search_expression=...) - Ciekawe spany stają się rekordami zbioru danych jednym kliknięciem lub wsadowo po 500 sztuk