Παρατηρησιμότητα και OpenTelemetry
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 με βάση το SDK
mistralai3.7.0: οι μέθοδοι ιχνηλάτησης βρίσκονται κάτω από τοclient.workflows.executions; οι ασύγχρονες εκδόσεις τους φέρουν το επίθεμα_async(η αναμονή της σύγχρονης έκδοσης αποτυγχάνει), τοexecution_idπερνάει ως όρισμα λέξης-κλειδιού, και οι αποκρίσεις εκθέτουν ταotel_trace_data,span_tree, καιevents(τα πεδίαspans,activity_count, ήerror_countπου διάβαζε η παλαιότερη έκδοση δεν υπάρχουν πλέον)· τοtraceparentπερνάει ως παράμετρος εκτέλεσης, καθώς η κεφαλίδα HTTP έχει καταργηθεί. Πηγές: Παρατηρησιμότητα ροών εργασίας · client-python.
Γιατί να παρατηρείτε τις ροές εργασίας σας
Μια ροή εργασίας σε παραγωγή μπορεί να αλυσιδώνει δεκάδες δραστηριότητες, να καλεί πολλαπλές εξωτερικές υπηρεσίες και να εκτελείται από λίγα δευτερόλεπτα έως αρκετές ημέρες. Χωρίς παρατηρησιμότητα, η διάγνωση ενός προβλήματος μοιάζει με την εύρεση μιας βελόνας σε μια θημωνιά: ξέρετε ότι η εκτέλεση απέτυχε, αλλά όχι σε ποιο βήμα, μετά από πόσες προσπάθειες, ή αν ο υπαίτιος είναι ο κώδικάς σας ή ένα API τρίτου μέρους. Η πλατφόρμα Workflows της Mistral ενσωματώνει εγγενώς το OpenTelemetry για να απαντήσει σε αυτό το ερώτημα: κάθε δραστηριότητα, κάθε σφάλμα και κάθε διάρκεια καταγράφεται ως ένα span σε ένα κατανεμημένο ίχνος, χωρίς να απαιτείται καμία instrumentation από την πλευρά σας.
Δύο έννοιες δομούν αυτό το μοντέλο. Το ίχνος (trace) αντιπροσωπεύει ολόκληρη τη διαδρομή μιας εκτέλεσης, από την αρχική ενεργοποίηση έως το τελικό αποτέλεσμα. Το span, από την άλλη πλευρά, είναι μια μεμονωμένη λειτουργία μέσα σε αυτό το ίχνος: κάθε δραστηριότητα δημιουργεί αυτόματα ένα, μεταφέροντας το όνομά της, τους χρόνους έναρξης και λήξης, τη διάρκεια εκτέλεσης, την κατάσταση (επιτυχία ή σφάλμα) και τυχόν προσαρμοσμένα χαρακτηριστικά. Αυτά τα spans σχηματίζουν μια ιεραρχία—το span της ροής εργασίας είναι ο γονέας και τα spans των δραστηριοτήτων είναι τα παιδιά του—η οποία αναπαράγει την πλήρη δομή της εκτέλεσης.
Ονομάστε τις δραστηριότητες για ευανάγνωση
Η παράμετρος name του διακοσμητή δραστηριότητας καθορίζει την ετικέτα που εμφανίζεται στα ίχνη. Είναι μια επένδυση δέκα δευτερολέπτων κατά τη συγγραφή που θα σας εξοικονομήσει πολύ χρόνο κατά τη διάρκεια ενός περιστατικού.
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"}
Βάλτε τον εαυτό σας στη θέση του μηχανικού βάρδιας που ανοίγει μια προβολή ιχνών στις 3 π.μ. Μεταξύ του fetch_user_data και του “Retrieve user profile”, το δεύτερο είναι άμεσα κατανοητό, ακόμη και σε κάποιον που δεν έχει διαβάσει ποτέ αυτόν τον κώδικα.
Ανάκτηση ιχνών προγραμματιστικά
Το SDK εκθέτει τρεις μεθόδους πρόσβασης κάτω από το client.workflows.executions· οι ασύγχρονες εκδόσεις τους φέρουν το επίθεμα _async. Η πρώτη επιστρέφει ακατέργαστα δεδομένα OpenTelemetry—spans, διάρκειες, χαρακτηριστικά, σχέσεις γονέα-παιδιού—επιτρέποντάς σας να τα επανεισαγάγετε στο δικό σας εργαλείο παρατηρησιμότητας (Jaeger, Grafana Tempo, κ.λπ.).
from mistralai.client import Mistral
client = Mistral()
# Ακατέργαστα δεδομένα OpenTelemetry για την εκτέλεση
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 # Πλήρες ίχνος, για επανεξαγωγή στο backend σας
Όταν θέλετε κυρίως να μάθετε αν η εκτέλεσηολοκληρώθηκε και πόσο χρόνο πήρε, η σύνοψη αρκεί. Περιλαμβάνει την κατάσταση, τη συνολική διάρκεια και το δέντρο spans, το οποίο μπορείτε να διατρέξετε αναδρομικά:
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"Total duration: {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)} event(s)")
for child in span.children or []:
display(child, depth + 1)
if summary.span_tree:
display(summary.span_tree)
Η τρίτη μέθοδος επιστρέφει μια χρονολογική λίστα συμβάντων εκτέλεσης:
response = await client.workflows.executions.get_workflow_execution_trace_events_async(
execution_id="exec_abc123def456",
include_internal_events=False, # Αποκλεισμός εσωτερικών συμβάντων πλατφόρμας
)
for event in response.events or []:
print(event)
Η παράμετρος include_internal_events=False φιλτράρει τα τεχνικά συμβάντα της πλατφόρμας, κρατώντας μόνο εκείνα από τη ροή εργασίας και τις δραστηριότητές σας. Σε μια ελαφρώς μεγάλη ροή εργασίας, η διαφορά στην ευανάγνωση είναι σημαντική. Για τα ίδια τα αρχεία καταγραφής—αυτά που εμφανίζονται στο Studio—το get_workflow_execution_logs τα επιστρέφει σελίδα προς σελίδα.
Κυριαρχήστε τη δειγματοληψία
Από προεπιλογή, όλα τα ίχνη εξάγονται: ο worker κάνει δειγματοληψία στο 100%. Για να ορίσετε το ID ιχνούς ή να ελέγξετε τη δειγματοληψία για μια εκτέλεση, περάστε ένα traceparent μορφής W3C στο σώμα του αιτήματος εκτέλεσης. Ο worker χρησιμοποιεί έναν δειγματολήπτη βασισμένο στον γονέα: ακολουθεί την απόφασή σας, η οποία μεταφέρεται από το τελευταίο πεδίο (01 για συλλογή, 00 για μη συλλογή).
execution = await client.workflows.execute_workflow_async(
workflow_identifier="my_workflow",
input={"data": "test"},
traceparent="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
)
Τα SDK της Mistral το κάνουν αυτό αυτόματα: με κάθε εκτέλεση, μεταδίδουν το traceparent του τρέχοντος span. Η passing του traceparent σε μια κεφαλίδα HTTP γίνεται ακόμα δεκτή αλλά έχει καταργηθεί, επειδή μια κεφαλίδα μπορεί να ξαναγραφτεί κατά τη μεταφορά· χρησιμοποιήστε instead την παράμετρο.
Παρακολούθηση σε παραγωγή
Πέντε δείκτες αρκούν για να κρατήσετε μια ροή εργασίας υπό έλεγχο: το ποσοστό επιτυχίας, δηλαδή το ποσοστό των εκτελέσεων που ολοκληρώνονται χωρίς σφάλμα· η μέση διάρκεια μιας πλήρους εκτέλεσης· οι διάρκειες P95 και P99, οι οποίες αποκαλύπτουν τις πιο αργές εκτελέσεις που ο μέσος όρος κρύβει· το ποσοστό επαναλήψεων ανά δραστηριότητα, του οποίου η ξαφνική άνοδος προδίδει μια ασταθή εξωτερική υπηρεσία πολύ πριν υποβαθμιστεί το ποσοστό επιτυχίας· και τέλος, ο εντοπισμός της πιο αργής δραστηριότητας, του σημείου συμφόρησής σας.
Επειδή τα ίχνη σέβονται το πρότυπο OpenTelemetry, τίποτα δεν σας υποχρεώνει να τα συμβουλεύεστε από το SDK: μπορούν να εξαχθούν στο Datadog μέσω του συλλέκτη OTel, στο Grafana και στο Tempo με τον ίδιο μηχανισμό, στο Jaeger για οπτικοποίηση κατανεμημένων ιχνών, ή στο New Relic μέσω του ειδικού εξαγωγέα του. Οι ροές εργασίας σας εντάσσονται έτσι στον πίνακα ελέγχου όπου ζει ήδη η υπόλοιπη υποδομή σας.
Αποσφαλμάτωση μιας αποτυχημένης ροής εργασίας
Αντιμέτωποι με μια αποτυχία, μια μεθοδική διαδικασία αποφεύγει τις εικασίες.
- Ανάκτηση του ID εκτέλεσης από τα αρχεία καταγραφής ή την απόκριση API
- Συμβουλευτείτε τη σύνοψη του ίχνους για να μάθετε την κατάσταση και να εντοπίσετε την ελαττωματική δραστηριότητα στο δέντρο spans
- Εξετάστε τα λεπτομερή συμβάντα για να κατανοήσετε την ακολουθία που οδήγησε στο σφάλμα
- Ελέγξτε τις επαναλήψεις: ξεκίνησε ξανά η δραστηριότητα; Πόσες φορές;
- Αναλύστε το μήνυμα σφάλματος: χρονικό όριο, σφάλμα δικτύου, επιχειρηματικό σφάλμα;
Τα δύο πρώτα βήματα μπορούν να αυτοματοποιηθούν σε λίγες γραμμές, χρησιμοποιώντας τη συνάρτηση display που είδαμε παραπάνω, δίνοντάς σας ένα επαναχρησιμοποιήσιμο εργαλείο διάγνωσης.
async def diagnose_failure(execution_id: str):
client = Mistral()
executions = client.workflows.executions
# Βήμα 1: Σύνοψη και δέντρο spans
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)
# Βήμα 2: Συμβάντα από τον κώδικά σας, με σειρά
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)
Ο αριθμός των προσπαθειών deserves ιδιαίτερη προσοχή: μια δραστηριότητα που αποτυγχάνει στην πρώτη προσπάθεια και μια που αποτυγχάνει μετά από πέντε επαναλήψεις αφηγούνται διαφορετικές ιστορίες και απαιτούν διαφορετικές διορθώσεις.
Ανακεφαλαίωση μαθήματος
Συγχαρητήρια, ολοκληρώσατε αυτό το μάθημα για τις Ροές Εργασίας της Mistral. Η διαδρομή σας οδήγησε από τη διαρκή ενορχήστρωση και τον μηχανισμό event sourcing στην εγκατάσταση του SDK (μαθήματα 1 έως 3), στη συνέχεια στη δημιουργία δραστηριοτήτων, ροών εργασίας και workers, στην ενεργοποίηση και τον έλεγχό τους (μαθήματα 4 έως 7). Τα μαθήματα 8 έως 11 έθεσαν τους δομικούς περιορισμούς—ντετερμινισμό, είσοδοι Pydantic, χρονικά όρια, περιορισμοί—πριν ανοίξουν σε προηγμένα μοτίβα παραλληλισμού και συνέχειας. Τα τελευταία τρία κάλυψαν τις πολιτικές επανάληψης, την απαίτηση για ασύγχρονο I/O και την παρατηρησιμότητα με το OpenTelemetry.
Η πλατφόρμα βρίσκεται σε Δημόσια Προεπισκόπηση: τα APIs και οι λειτουργίες ενδέχεται να εξελιχθούν. Ελέγχετε τακτικά την επίσημη τεκμηρίωση στο docs.mistral.ai/workflows για να παρακολουθείτε τις ενημερώσεις.
Βασικά σημεία
- Κάθε δραστηριότητα δημιουργεί αυτόματα spans OpenTelemetry με όνομα, διάρκεια και κατάσταση
- Ονομάστε τις δραστηριότητές σας με την παράμετρο
nameγια να διευκολύνετε την αποσφαλμάτωση - Τρεις μέθοδοι πρόσβασης στα ίχνη, κάτω από το
client.workflows.executions: ακατέργαστο OTel, σύνοψη (κατάσταση, διάρκεια, δέντρο spans) και λεπτομερή συμβάντα - Η δειγματοληψία ελέγχεται από την παράμετρο
traceparentτης εκτέλεσης (100% από προεπιλογή· η κεφαλίδα HTTP έχει καταργηθεί) - Σε παραγωγή, παρακολουθείτε το ποσοστό επιτυχίας, τη διάρκεια και το ποσοστό επαναλήψεων
- Τα τυπικά ίχνη OTel είναι εξαγώγιμα στο Datadog, Grafana, Jaeger ή New Relic
Δοκιμάστε τις γνώσεις σας
Διαρκείς ροές εργασίας: κανόνες του κινητήρα πριν την παραγωγή.
1. Τι εγγυάται η πλατφόρμα Mistral Workflows;
Απάντηση: Διαρκότητα: μια ροή εργασίας επιβιώνει από αποτυχίες και επαναλαμβάνεται από εκεί που σταμάτησε—η ενορχήστρωση μεγάλης διάρκειας γίνεται αξιόπιστη εξ ορισμού.
2. Δραστηριότητα, ροή εργασίας, worker: ποιος κάνει τι;
Απάντηση: Η δραστηριότητα είναι η μονάδα εργασίας (εξωτερική κλήση, υπολογισμός), η ροή εργασίας ενορχηστρώνει τις δραστηριότητες, ο worker εκτελεί—ο διαχωρισμός που επιτρέπει την επανάληψη και την κλιμάκωση.
3. Τι επιβάλλει ο κανόνας του ντετερμινισμού;
Απάντηση: Ο κώδικας της ροής εργασίας πρέπει να είναι επαναλήψιμος πανομοιότυπα: όχι τυχαιότητα ή άμεση πρόσβαση στο ρολόι στην ενορχήστρωση—τα μη ντετερμινιστικά αποτελέσματα ζουν στις δραστηριότητες.
4. Πώς αντιμετωπίζονται οι παροδικές αποτυχίες;
Απάντηση: Μέσω της πολιτικής επανάληψης δραστηριότητας (προσπάθειες, backoff) και των χρονικών ορίων—η αποτυχία είναι μια κανονική περίπτωση, που αντιμετωπίζεται δηλωτικά και όχι χειροκίνητα.
5. Τι φέρνει η ενσωμάτωση του OpenTelemetry;
Απάντηση: Τυπική παρατηρησιμότητα: ίχνη εκτέλεσης, μετρικές και συσχέτιση με το υπόλοιπο σύστημά σας—απαραίτητο για τη λειτουργία ροών εργασίας σε παραγωγή.
Διαρκότητα, ντετερμινισμός, επανάληψη, παρατηρησιμότητα: τέσσερις κανόνες που συγκρατούν τις μακροχρόνιες ενορχηστρώσεις—ο κινητήρας χειρίζεται τα υπόλοιπα.