Concepts de trace

Le traçage est une technique d’observabilité qui capture le flux d’exécution complet d’une requête à travers votre application. Contrairement à la journalisation traditionnelle qui enregistre des événements isolés, le traçage crée une carte détaillée de la façon dont les données circulent dans vos systèmes et enregistre chaque opération en cours de route.

Les applications GenAI exécutent des workflows complexes en plusieurs étapes qui combinent plusieurs composants tels que des LLM, des récupérateurs, des outils et des agents. Le traçage rend ces workflows déboguables en capturant le flux d'exécution complet.

Structure de la trace

Une trace MLflow comprend deux objets principaux :

1. Trace.info de type TraceInfo: Métadonnées décrivant l’origine, le statut et le temps d’exécution de la trace. TraceInfo contient également des tags. Les tags sont des paires clé-valeur fournies par l’utilisateur, la session et le développeur que vous pouvez utiliser pour rechercher ou filtrer des traces.

2. Trace.data de type TraceData: La charge utile réelle contenant des objets Span instrumentés qui capturent l'exécution étape par étape de votre application de l'entrée à la sortie.

Les traces MLflow sont compatibles avec les spécifications OpenTelemetry, une norme des secteurs d'activité largement adoptée pour l'observabilité. Les traces restent interopérables avec d'autres outils d'observabilité compatibles avec OpenTelemetry, tandis que MLflow étend le modèle OpenTelemetry avec des structures et attributs spécifiques à l'IA générative.

Informations de suivi

TraceInfo fournit des métadonnées légères sur la trace globale. Les champs clés comprennent :

Champ	Description
trace_id	Identifiant unique pour la trace
trace_location	Où la trace est stockée : un emplacement de trace Unity Catalog (recommandé), une expérimentation MLflow ou une table d'inférence Databricks
request_time	start time of the trace en millisecondes
state	État de la trace : OK, ERROR, IN_PROGRESS ou STATE_UNSPECIFIED
execution_duration	Durée de la trace en millisecondes
request_preview	Aperçu encodé en JSON de l'entrée (entrée de span racine)
response_preview	Aperçu au format JSON de la sortie (sortie de la portée racine)
tags	Paires clé-valeur pour le filtrage et la recherche de traces

Champ	Description
trace_id	Identifiant unique pour la trace
trace_location	Où la trace est stockée : un emplacement de trace Unity Catalog (recommandé), une expérimentation MLflow ou une table d'inférence Databricks
request_time	start time of the trace en millisecondes
state	État de la trace : OK, ERROR, IN_PROGRESS ou STATE_UNSPECIFIED
execution_duration	Durée de la trace en millisecondes
request_preview	Aperçu encodé en JSON de l'entrée (entrée de span racine)
response_preview	Aperçu au format JSON de la sortie (sortie de la portée racine)
tags	Paires clé-valeur pour le filtrage et la recherche de traces

TraceData

L’objet TraceData est un conteneur d’objets Span où les détails d’exécution sont stockés. Chaque étendue capture des informations sur une Opération spécifique, notamment :

• Requêtes et réponses
• Mesures de latence.
• Messages LLM et paramètres d'outil
• Documents récupérés et contexte
• Métadonnées et attributs

Les spans forment une structure hiérarchique grâce à des connexions parent-enfant, créant un arbre qui représente le flux d'exécution de votre application.

Tags

Les tags sont des paires clé-valeur mutables attachées aux traces pour l'organisation et le filtrage. MLflow définit des tags standard pour les cas d'utilisation courants :

• mlflow.trace.session: Identifiant de session pour regrouper les traces associées
• mlflow.trace.user: Identifiant utilisateur pour le suivi des interactions par utilisateur
• mlflow.source.name: Point d'entrée ou script qui a généré la trace
• mlflow.source.git.commit: Hachage de commit Git du code source (le cas échéant)
• mlflow.source.type: Type de source (PROJECT, NOTEBOOK, etc.)

Vous pouvez également ajouter des tags personnalisés pour vos besoins spécifiques. En savoir plus dans Ajouter du contexte aux traces et Joindre des balises/métadonnées personnalisées.

Storage Layout

Une trace appartient toujours à une expérimentation MLflow, mais vous choisissez le backend qui stocke physiquement les données de trace :

• **Tables Delta OTel Unity Catalog (recommandé)** : Pour monter en charge et pour la gouvernance, pointez votre experimentation vers un emplacement de trace Unity Catalog. Les traces sont stockées dans des tables Delta au format OpenTelemetry sans limite par experimentation, régies par les autorisations Unity Catalog et interrogeables avec SQL. Voir Stocker les traces OpenTelemetry dans Unity Catalog.
• Backend d'expérimentation géré : La valeur default lorsqu'aucun emplacement de trace Unity Catalog n'est configuré. TraceInfo est stocké dans une base de données relationnelle sous forme de lignes indexées, ce qui permet des requêtes rapides pour la recherche et le filtrage des traces. TraceData (les spans) sont stockées dans le stockage d'artefacts plutôt que dans la base de données relationnelle, car les spans sont plus grandes. Cela permet aux query de rester rapides même lorsque le volume de traces augmente.

Traces actives ou terminées

Une trace active est une trace que MLflow est en train d'écrire, par exemple lorsqu'une fonction décorée avec @mlflow.trace est en cours d'exécution. Une fois que la fonction décorée se termine, la trace est terminée, mais vous pouvez encore l'annoter avec de nouvelles données.

Pour travailler avec des traces actives ou récentes, utilisez ces méthodes :

• mlflow.get_active_trace_id(): renvoie l'ID de la trace actuellement active.
• mlflow.get_last_active_trace_id(): retourne l'ID de la trace terminée la plus récente.

Ressources supplémentaires

• Concepts d'étendue – Apprenez-en davantage sur les étendues et la façon dont elles capturent les opérations individuelles.
• Commencer : MLflow Tracing pour GenAI (Databricks Notebook) - Obtenez une expérience pratique avec le traçage dans un Notebook.