Observabilité des workflows

Ce guide explique comment les données de télémétrie (logs, traces et métriques) sont exportées, ainsi que l'utilisation des traces OpenTelemetry pour les diagnostics au niveau de l'exécution.

Par défaut, le worker exporte les logs, traces et métriques OpenTelemetry vers la plateforme d'observabilité hébergée par Mistral. Aucune configuration n'est requise : la télémétrie est authentifiée avec votre clé API Mistral et envoyée à l'endpoint de télémétrie de Mistral. C'est ce qui permet d'afficher directement dans Studio, sur la page d'exécution, les logs et traces de vos workflows.

Vous pouvez également envoyer les données de télémétrie vers votre propre pile d’observabilité ou les désactiver. Consultez la section Configurer l’export des données de télémétrie à la fin de cette page.

Les traces capturent les détails d'exécution (spans, timings, erreurs) et sont optimisées pour le débogage et l'analyse de performance. Elles sont indépendantes des événements de tâches personnalisés.

Les logs d’exécution sont également disponibles dans Studio. Ouvrez Studio›Workflows›Executions ↗ et sélectionnez une exécution pour consulter ses logs sur la page correspondante.

Les activités génèrent automatiquement des spans. Utilisez le paramètre name pour les rendre plus lisibles :

@workflows.activity(name="Processing customer emails")
async def process_emails(params: ActivityParams) -> ActivityResult:
    # Your activity code

@workflows.activity(name="Processing customer emails")
async def process_emails(params: ActivityParams) -> ActivityResult:
    # Your activity code

Par défaut, toutes les traces sont exportées (le worker échantillonne à un taux de 100 %). Pour contrôler l'échantillonnage, transmettez un en-tête traceparent au point d'entrée de votre workflow (ou à la périphérie de l'API) : le worker utilise un échantillonneur basé sur le parent, il respecte donc la décision d'échantillonnage en amont. Cela vous permet de forcer l'échantillonnage (activation/désactivation) et de propager la trace parente de manière cohérente.

Trois méthodes sont disponibles pour récupérer les données de trace d'une exécution donnée :

• get_workflow_execution_trace_otel() : renvoie les données brutes de trace OpenTelemetry (spans avec temporisations, attributs et relations parent-enfant). Utilisez cette méthode pour alimenter vos traces dans votre propre backend d’observabilité (Jaeger, Grafana Tempo, etc.).
• get_workflow_execution_trace_summary() : renvoie un résumé de haut niveau de l’exécution (durée totale, nombre d’activités, nombre d’erreurs). Utile pour les tableaux de bord et les vérifications de statut rapides.
• get_workflow_execution_trace_events() : renvoie une liste chronologique des événements de l’exécution. Définissez include_internal_events=False pour filtrer les événements internes à la plateforme et ne voir que ceux de votre workflow et de vos activités.

from mistralai.client import Mistral

client = Mistral(api_key="your_api_key")

# Get raw OpenTelemetry trace data (spans, timings, attributes)
trace = client.workflows.executions.get_workflow_execution_trace_otel(
    execution_id=execution_id,
)

# Get high-level summary (duration, activity count, errors)
summary = client.workflows.executions.get_workflow_execution_trace_summary(
    execution_id=execution_id,
)

# Get chronological event list
events = client.workflows.executions.get_workflow_execution_trace_events(
    execution_id=execution_id,
    include_internal_events=False,  # Hide system events
)

from mistralai.client import Mistral

client = Mistral(api_key="your_api_key")

# Get raw OpenTelemetry trace data (spans, timings, attributes)
trace = client.workflows.executions.get_workflow_execution_trace_otel(
    execution_id=execution_id,
)

# Get high-level summary (duration, activity count, errors)
summary = client.workflows.executions.get_workflow_execution_trace_summary(
    execution_id=execution_id,
)

# Get chronological event list
events = client.workflows.executions.get_workflow_execution_trace_events(
    execution_id=execution_id,
    include_internal_events=False,  # Hide system events
)

Les logs d’exécution (les mêmes que ceux affichés dans Studio) peuvent également être récupérés par programme :

• get_workflow_execution_logs() : renvoie une page d’enregistrements de logs pour une exécution. Filtrez avec run_id, activity_id et une plage horaire (after, before), choisissez le tri de la première page avec order (asc ou desc), et paginez avec cursor et limit.
• stream_workflow_execution_logs() : diffuse les enregistrements de logs en direct via Server-Sent Events (SSE).

# Get the first page of execution logs (oldest first)
logs = client.workflows.executions.get_workflow_execution_logs(
    execution_id=execution_id,
    order="asc",
    limit=50,
)

# Fetch the next page using the returned cursor
if logs.next_cursor:
    next_page = client.workflows.executions.get_workflow_execution_logs(
        execution_id=execution_id,
        cursor=logs.next_cursor,
    )

# Get the first page of execution logs (oldest first)
logs = client.workflows.executions.get_workflow_execution_logs(
    execution_id=execution_id,
    order="asc",
    limit=50,
)

# Fetch the next page using the returned cursor
if logs.next_cursor:
    next_page = client.workflows.executions.get_workflow_execution_logs(
        execution_id=execution_id,
        cursor=logs.next_cursor,
    )

Par défaut, tous les signaux sont exportés vers Mistral AI (voir la section Configuration de la télémétrie ci-dessus). Vous pouvez rediriger des signaux individuels vers votre propre endpoint OTLP, router l’intégralité des données vers un seul endpoint ou désactiver complètement l’export.

Pour envoyer la télémétrie du worker vers votre propre stack d'observabilité, orientez un ou plusieurs signaux vers votre propre endpoint OTLP. Chaque signal est acheminé indépendamment :

Indiquez l’endpoint OTLP HTTP de base (par exemple https://otel.example.com). L’application worker ajoute automatiquement le chemin standard du signal (/v1/traces, /v1/metrics ou /v1/logs).

Les signaux que vous ne redirigez pas continuent d'être envoyés à Mistral, et restent donc visibles dans Studio. Lorsque vous définissez un endpoint personnalisé, le worker n'attache plus votre clé API Mistral pour ce signal : vous devez donc l'authentifier vous-même.

Pour authentifier un endpoint personnalisé, utilisez la variable d'en-tête OTLP spécifique au signal (OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_EXPORTER_OTLP_METRICS_HEADERS ou OTEL_EXPORTER_OTLP_LOGS_HEADERS). Par exemple, pour envoyer uniquement les métriques à votre propre stack tout en conservant les logs et traces dans Studio :

OTEL_METRICS_ENDPOINT=https://otel.example.com
OTEL_EXPORTER_OTLP_METRICS_HEADERS=Authorization=Bearer <your-token>

OTEL_METRICS_ENDPOINT=https://otel.example.com
OTEL_EXPORTER_OTLP_METRICS_HEADERS=Authorization=Bearer <your-token>

Pour acheminer tous les signaux vers un seul endpoint, définissez OTEL_ENDPOINT. Cela envoie les traces, métriques et logs à cet endpoint unique et n'attache aucune authentification Mistral. Utilisez les variables par signal ci-dessus lorsque vous avez besoin de destinations différentes ou souhaitez conserver certains signaux dans Studio.

Vous pouvez désactiver l'export entièrement ou par signal :