Obserwowalność i OpenTelemetry
Na tej stronie
Zaktualizowano 2 listopada 2026 w oparciu o SDK
mistralaiw wersji 3.7.0: metody śledzenia znajdują się podclient.workflows.executions; ich wersje asynchroniczne mają przyrostek_async(oczekiwanie na wersję synchroniczną kończy się niepowodzeniem),execution_idjest przekazywane jako argument nazwany, a odpowiedzi udostępniająotel_trace_data,span_treeorazevents(polaspans,activity_countluberror_countodczytywane przez starszą wersję już nie istnieją);traceparentjest przekazywane jako parametr wykonania, ponieważ nagłówek HTTP jest przestarzały. Źródła: Workflow observability · client-python.
Dlaczego warto obserwować swoje workflow
Workflow w środowisku produkcyjnym może łączyć dziesiątki działań, wywoływać wiele usług zewnętrznych i działać od kilku sekund do kilku dni. Bez obserwowalności diagnozowanie problemu przypomina szukanie igły w stogu siana: wiesz, że wykonanie się nie powiodło, ale nie wiesz, na którym etapie, po ilu próbach i czy winny jest Twój kod, czy API strony trzeciej. Platforma Mistral Workflows natywnie integruje się z OpenTelemetry, aby odpowiedzieć na to pytanie: każde działanie, każdy błąd i każdy czas trwania są rejestrowane jako span w śladzie rozproszonym, bez konieczności instrumentacji z Twojej strony.
Dwa pojęcia strukturują ten model. Ślad (trace) reprezentuje całą podróż wykonania, od początkowego wyzwalacza do końcowego rezultatu. Span z kolei to pojedyncza operacja w ramach tego śladu: każde działanie automatycznie generuje jeden span, zawierający jego nazwę, czas rozpoczęcia i zakończenia, czas trwania wykonania, status (sukces lub błąd) oraz wszelkie niestandardowe atrybuty. Te spany tworzą hierarchię – span workflow jest rodzicem, a spany działań są jego dziećmi – co odwzorowuje pełną strukturę wykonania.
Nazywaj działania dla czytelności
Parametr name dekoratora działania określa etykietę widoczną w śladach. To inwestycja dziesięciu sekund podczas pisania kodu, która zaoszczędzi Ci mnóstwo czasu podczas incydentu.
import mistralai.workflows as workflows
@workflows.activity(name="Extract source text")
async def extraire_texte(url: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(url)
return {"texte": response.text}
@workflows.activity(name="Mistral sentiment analysis")
async def analyser_sentiment(texte: str) -> dict:
client = Mistral()
response = await client.chat.complete_async(
model="mistral-large-latest",
messages=[
{"role": "system", "content": "Analyze the sentiment."},
{"role": "user", "content": texte}
]
)
return {"sentiment": response.choices[0].message.content}
@workflows.activity(name="Send email notification")
async def envoyer_notification(destinataire: str, contenu: str) -> dict:
# ...
return {"status": "sent"}
Wciel się w rolę inżyniera dyżurnego, który o 3 nad ranem otwiera widok śladu. Pomiędzy fetch_user_data a „Pobierz profil użytkownika“ ta druga opcja jest natychmiast zrozumiała, nawet dla kogoś, kto nigdy nie czytał tego kodu.
Programowe pobieranie śladów
SDK udostępnia trzy metody dostępu pod client.workflows.executions; ich wersje asynchroniczne mają przyrostek _async. Pierwsza zwraca surowe dane OpenTelemetry – spany, czasy trwania, atrybuty, relacje rodzic-dziecko – co pozwala na ponowne ingestowanie ich do własnego narzędzia obserwowalności (Jaeger, Grafana Tempo itp.).
from mistralai.client import Mistral
client = Mistral()
# Surowe dane OpenTelemetry dla wykonania
trace = await client.workflows.executions.get_workflow_execution_trace_otel_async(
execution_id="exec_abc123def456"
)
print(f"OTel Trace: {trace.otel_trace_id}")
otel_data = trace.otel_trace_data # Pełny ślad, do ponownego eksportu do Twojego backendu
Gdy zależy Ci głównie na tym, czy wykonanie się powiodło i ile trwało, podsumowanie wystarczy. Zawiera status, całkowity czas trwania oraz drzewo spanów, które możesz przetwarzać rekurencyjnie:
summary = await client.workflows.executions.get_workflow_execution_trace_summary_async(
execution_id="exec_abc123def456"
)
print(f"Workflow: {summary.workflow_name} — status {summary.status}")
print(f"Całkowity czas trwania: {summary.total_duration_ms} ms")
def display(span, depth=0):
end = span.end_time_unix_nano or span.start_time_unix_nano
duration_ms = (end - span.start_time_unix_nano) / 1e6
print(f"{' ' * depth}{span.name}: {duration_ms:.0f} ms, {len(span.events)} zdarzeń")
for child in span.children or []:
display(child, depth + 1)
if summary.span_tree:
display(summary.span_tree)
Trzecia metoda zwraca chronologiczną listę zdarzeń wykonania:
response = await client.workflows.executions.get_workflow_execution_trace_events_async(
execution_id="exec_abc123def456",
include_internal_events=False, # Wyklucz wewnętrzne zdarzenia platformy
)
for event in response.events or []:
print(event)
Parametr include_internal_events=False filtruje techniczne zdarzenia platformy, pozostawiając tylko te pochodzące z Twojego workflow i działań. Przy nieco dłuższym workflow różnica w czytelności jest znaczna. Co do samych logów – tych wyświetlanych w Studio – metoda get_workflow_execution_logs zwraca je strona po stronie.
Opanuj próbkowanie
Domyślnie wszystkie ślady są eksportowane: worker próbkuję w 100%. Aby ustawić ID śladu lub kontrolować próbkowanie dla wykonania, przekaż traceparent w formacie W3C w treści żądania wykonania. Worker używa sampleru opartego na rodzicu: podąża za Twoją decyzją, niesioną przez ostatnie pole (01 aby zbierać, 00 aby nie zbierać).
execution = await client.workflows.execute_workflow_async(
workflow_identifier="my_workflow",
input={"data": "test"},
traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)
SDK Mistral robią to automatycznie: przy każdym wykonaniu przekazują traceparent bieżącego spanu. Przekazywanie traceparent w nagłówku HTTP jest nadal akceptowane, ale przestarzałe, ponieważ nagłówek może zostać przepisany w tranzycie; zamiast tego użyj parametru.
Monitoruj w produkcji
Pięć wskaźników wystarczy, aby utrzymać workflow pod kontrolą: wskaźnik sukcesu, czyli procent wykonań kończących się bez błędu; średni czas trwania pełnego wykonania; czasy trwania P95 i P99, które ujawniają najwolniejsze wykonania ukryte przez średnią; wskaźnik ponownych prób na działanie, którego nagły wzrost zdradza niestabilność usługi zewnętrznej na długo przed pogorszeniem wskaźnika sukcesu; oraz wreszcie identyfikacja najwolniejszego działania, czyli Twojego wąskiego gardła.
Ponieważ ślady przestrzegają standardu OpenTelemetry, nic nie zmusza Cię do ich przeglądania z poziomu SDK: można je eksportować do Datadog poprzez jego kolektor OTel, do Grafany i Tempo tym samym mechanizmem, do Jaegera w celu wizualizacji śladów rozproszonych lub do New Relic poprzez dedykowany eksporter. Twoje workflow dołączają tym samym do dashboardu, w którym znajduje się już reszta Twojej infrastruktury.
Debuguj nieudane workflow
W obliczu niepowodzenia metodyczna procedura pozwala uniknąć zgadywania.
- Pobierz ID wykonania z logów lub odpowiedzi API
- Skonsultuj podsumowanie śladu, aby poznać status i zlokalizować wadliwe działanie w drzewie spanów
- Zbadaj szczegółowe zdarzenia, aby zrozumieć sekwencję prowadzącą do błędu
- Sprawdź ponowne próby: czy działanie zostało uruchomione ponownie? Ile razy?
- Przeanalizuj komunikat błędu: timeout, błąd sieci, błąd biznesowy?
Dwa pierwsze kroki można zautomatyzować w kilku liniach kodu, używając funkcji display pokazanej powyżej, co daje Ci wielokrotnego użytku narzędzie diagnostyczne.
async def diagnose_failure(execution_id: str):
client = Mistral()
executions = client.workflows.executions
# Krok 1: Podsumowanie i drzewo spanów
summary = await executions.get_workflow_execution_trace_summary_async(execution_id=execution_id)
print(f"Status: {summary.status}")
if summary.span_tree:
display(summary.span_tree)
# Krok 2: Zdarzenia z Twojego kodu, w kolejności
response = await executions.get_workflow_execution_trace_events_async(
execution_id=execution_id,
include_internal_events=False,
)
for event in response.events or []:
print(event)
Liczba prób zasługuje na szczególną uwagę: działanie, które zawodzi przy pierwszej próbie, i takie, które zawodzi po pięciu ponownych próbach, opowiadają różne historie i wymagają innych napraw.
Podsumowanie kursu
Gratulacje, ukończyłeś ten kurs dotyczący Mistral Workflows. Podróż zaprowadziła Cię od trwałej orkiestracji i mechanizmu event sourcingu przez instalację SDK (lekcje 1–3), aż po tworzenie działań, workflow i workerów, ich wyzwalanie i testowanie (lekcje 4–7). Lekcje 8–11 przedstawiły ograniczenia strukturalne – determinizm, dane wejściowe Pydantic, timeouty, limity – zanim otworzyły drogę do zaawansowanych wzorców paralelizmu i kontynuacji. Ostatnie trzy obejmowały polityki ponownych prób, wymóg asynchronicznego I/O oraz obserwowalność z OpenTelemetry.
Platforma znajduje się w fazie Public Preview: API i funkcje mogą ewoluować. Regularnie sprawdzaj oficjalną dokumentację pod adresem docs.mistral.ai/workflows, aby śledzić aktualizacje.
Kluczowe wnioski
- Każde działanie automatycznie generuje spany OpenTelemetry z nazwą, czasem trwania i statusem
- Nadawaj nazwy działaniom za pomocą parametru
name, aby ułatwić debugowanie - Trzy metody dostępu do śladów pod
client.workflows.executions: surowe dane OTel, podsumowanie (status, czas trwania, drzewo spanów) oraz szczegółowe zdarzenia - Próbkowanie jest kontrolowane przez parametr
traceparentwykonania (domyślnie 100%; nagłówek HTTP jest przestarzały) - W produkcji monitoruj wskaźnik sukcesu, czas trwania i wskaźnik ponownych prób
- Standardowe ślady OTel można eksportować do Datadog, Grafany, Jaegera lub New Relic
Sprawdź swoją wiedzę
Trwałe workflow: zasady silnika przed produkcją.
1. Co gwarantuje platforma Mistral Workflows?
Odpowiedź: Trwałość: workflow przetrwa awarie i wznowi działanie od momentu przerwania – długotrwała orkiestracja staje się niezawodna z założenia.
2. Działanie, workflow, worker: kto co robi?
Odpowiedź: Działanie to jednostka pracy (wywołanie zewnętrzne, obliczenie), workflow orkiestruje działania, worker wykonuje – to rozdzielenie umożliwia wznawianie i skalowanie.
3. Co narzuca zasada determinizmu?
Odpowiedź: Kod workflow musi być możliwy do identycznego odtworzenia: brak losowości lub bezpośredniego dostępu do zegara w orkiestracji – niedeterministyczne efekty żyją w działaniach.
4. Jak obsługiwane są przejściowe awarie?
Odpowiedź: Poprzez politykę ponownych prób działania (liczba prób, backoff) i timeouty – awaria jest przypadkiem normalnym, obsługiwanym deklaratywnie, a nie ręcznie.
5. Co wnosi integracja z OpenTelemetry?
Odpowiedź: Standardową obserwowalność: ślady wykonania, metryki i korelację z resztą systemu – niezbędne do operowania workflow w produkcji.
Trwałość, determinizm, ponowne próby, obserwowalność: cztery zasady spajające długie orkiestracje – silnik zajmuje się resztą.