Przejdź do głównej treści
Polski— Wybierz język
Menu

Obserwowalność i OpenTelemetry

Lekcja 14 z 14 Zaktualizowano 2 listopada 2026 Zaawansowany
Na tej stronie
  1. Dlaczego warto obserwować swoje workflow
  2. Nazywaj działania dla czytelności
  3. Programowe pobieranie śladów
  4. Opanuj próbkowanie
  5. Monitoruj w produkcji
  6. Debuguj nieudane workflow
  7. Podsumowanie kursu
  8. Kluczowe wnioski
  9. Sprawdź swoją wiedzę

Zaktualizowano 2 listopada 2026 w oparciu o SDK mistralai w wersji 3.7.0: metody śledzenia znajdują się pod client.workflows.executions; ich wersje asynchroniczne mają przyrostek _async (oczekiwanie na wersję synchroniczną kończy się niepowodzeniem), execution_id jest przekazywane jako argument nazwany, a odpowiedzi udostępniają otel_trace_data, span_tree oraz events (pola spans, activity_count lub error_count odczytywane przez starszą wersję już nie istnieją); traceparent jest 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.

  1. Pobierz ID wykonania z logów lub odpowiedzi API
  2. Skonsultuj podsumowanie śladu, aby poznać status i zlokalizować wadliwe działanie w drzewie spanów
  3. Zbadaj szczegółowe zdarzenia, aby zrozumieć sekwencję prowadzącą do błędu
  4. Sprawdź ponowne próby: czy działanie zostało uruchomione ponownie? Ile razy?
  5. 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 traceparent wykonania (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ą.