Tutoriel : Rechercher des traces par programme

Ouvrir dans Databricks

Ce tutoriel fournit des exemples simples pour commencer avec mlflow.search_traces(). Pour plus de détails sur la recherche de traces, consultez Rechercher des traces par programme.

Configuration de l'environnement

Installez les packages requis :

mlflow[databricks]Utilisez la dernière version de MLflow pour obtenir davantage de fonctionnalités et d'améliorations.
openai: Cette application utilisera le client de l'API OpenAI pour appeler les modèles hébergés par Databricks.

Python
%pip install -qq --upgrade "mlflow[databricks]>=3.1.0" openai
dbutils.library.restartPython()

Créez une Experimentation MLflow. Si vous utilisez un Notebook Databricks, vous pouvez ignorer cette étape et utiliser l'Experimentation Notebook par default. Sinon, suivez le guide de démarrage rapide de la configuration de l'environnement pour créer l'Experimentation et vous connecter au serveur MLflow Tracking.

Générer des traces pour l'analyse

Cette application simple génère des traces à utiliser avec search_traces().

Python

import mlflow
from databricks_openai import DatabricksOpenAI

mlflow.openai.autolog()

@mlflow.trace
def my_app(message: str) -> str:
    # Create an OpenAI client that is connected to Databricks-hosted LLMs
    client = DatabricksOpenAI()

    response = client.chat.completions.create(
        model="databricks-claude-sonnet-4",
        messages=[
            {
                "role": "system",
                "content": "You are a helpful assistant. Give brief, 1-2 sentence responses.",
            },
            {
                "role": "user",
                "content": message,
            },
        ]
    )

    # Add examples of custom metadata and tags
    mlflow.update_current_trace(
        metadata={
            &quot;mlflow.trace.user&quot;: 'name@my_company.com',
        },
        tags={
            &quot;environment&quot;: &quot;production&quot;,
        },
    )

    return response.choices[0].message.content

Python
my_app("What is MLflow and how does it help with GenAI?")
my_app("What is ML vs. AI?")
my_app("What is MLflow and how does it help with machine learning?")

Référence rapide

Python
# Search by status
mlflow.search_traces(filter_string="trace.status = 'OK'")
mlflow.search_traces(filter_string="trace.status = 'ERROR'")

# Search by time
mlflow.search_traces(filter_string="trace.timestamp_ms > 1749006880539")
mlflow.search_traces(filter_string="trace.execution_time_ms > 2500")

# Search by metadata
mlflow.search_traces(filter_string="metadata.`mlflow.trace.user` = 'name@my_company.com'")

# Search by tags
mlflow.search_traces(filter_string="tag.environment = 'production'")
mlflow.search_traces(filter_string="tag.`mlflow.traceName` = 'my_app'")

# Combined filters (AND only)
mlflow.search_traces(
    filter_string="trace.status = 'OK' AND tag.environment = 'production'"
)

traces = mlflow.search_traces()
traces

mlflow.search_traces() renvoie un DataFrame pandas ou une liste d'Trace objets avec ces champs :

Python
list(traces.columns)

Output
['trace_id',
 'trace',
 'client_request_id',
 'state',
 'request_time',
 'execution_duration',
 'request',
 'response',
 'trace_metadata',
 'tags',
 'spans',
 'assessments']

Exemples de recherche

Lorsque vous exécutez ce tutoriel, les cellules de code ci-dessous afficheront les résultats de recherche.

Rechercher par statut

La recherche par statut vous permet de trouver des traces réussies, échouées ou en cours.

Python
mlflow.search_traces(filter_string="trace.status = 'OK'")

Python
mlflow.search_traces(filter_string="trace.status != 'ERROR'")

Rechercher par Timestamp

Le temps doit être spécifié en millisecondes, en utilisant des Timestamp Unix.

Rechercher les traces récentes des 5 dernières minutes :

Python
import time
from datetime import datetime

current_time_ms = int(time.time() * 1000)
five_minutes_ago = current_time_ms - (5 * 60 * 1000)
mlflow.search_traces(
    filter_string=f"trace.timestamp_ms > {five_minutes_ago}"
)

Rechercher sur une plage de dates :

Python
start_date = int(datetime(2026, 1, 1).timestamp() * 1000)
end_date = int(datetime(2026, 1, 31).timestamp() * 1000)
mlflow.search_traces(
    filter_string=f"trace.timestamp_ms > {start_date} AND attributes.timestamp_ms < {end_date}"
)

Vous pouvez également utiliser l'alias 'Timestamp' au lieu de 'timestamp_ms' :

Python
mlflow.search_traces(filter_string=f"trace.timestamp > {five_minutes_ago}")

Rechercher par temps d'exécution

Trouvez les traces lentes :

Python
mlflow.search_traces(filter_string="trace.execution_time_ms > 2500")

Vous pouvez également utiliser l'alias 'latency' au lieu de 'execution_time_ms' :

Python
mlflow.search_traces(filter_string="trace.latency > 1000")

Recherche par métadonnées

N’oubliez pas d’utiliser les apostrophes inversées pour les noms de métadonnées avec des points.

Recherchez les métadonnées personnalisées pour un utilisateur spécifique :

Python
mlflow.search_traces(filter_string="metadata.`mlflow.trace.user` = 'name@my_company.com'")

Rechercher par tags

N'oubliez pas d'utiliser les guillemets inversés pour les noms de balises avec des points.

Rechercher les tags système :

Python
mlflow.search_traces(
    filter_string="tag.`mlflow.traceName` = 'my_app'"
)

Rechercher les tags personnalisés définis à l'aide de mlflow.update_current_trace():

Python
mlflow.search_traces(filter_string="tag.environment = 'production'")

Filtres complexes

Seul AND est pris en charge, pas OR.

Trouver les traces de production récentes réussies :

Python
current_time_ms = int(time.time() * 1000)
one_hour_ago = current_time_ms - (60 * 60 * 1000)

mlflow.search_traces(
    filter_string=f"trace.status = 'OK' AND "
                  f"trace.timestamp_ms > {one_hour_ago} AND "
                  f"tag.environment = 'production'"
)

Rechercher des traces rapides d'un utilisateur spécifique :

Python
mlflow.search_traces(
    filter_string="trace.execution_time_ms < 2500 AND "
                  "metadata.`mlflow.trace.user` = 'name@my_company.com'"
)

Trouvez les traces d'une fonction spécifique qui dépassent un threshold de performance :

Python
mlflow.search_traces(
    filter_string="tag.`mlflow.traceName` = 'my_app' AND "
                  "trace.execution_time_ms > 1000"
)

Étapes suivantes

En général, vous appellerez mlflow.search_traces() pour extraire un ensemble de traces, puis effectuerez une analyse ou un traitement supplémentaire du DataFrame ou de la liste d'objets Trace renvoyé(e).

Pour des exemples plus avancés, voir :

Tutoriel : Tracer et analyser les utilisateurs et les environnements - Exécutez un exemple d'ajout de métadonnées de contexte aux traces et d'analyse des résultats
Exemples : analyse de trace - Voir une variété d'exemples d'analyse de trace

Exemple de Notebook

Tutoriel : rechercher des traces par programmation

Ouvrir le notebook dans un nouvel onglet Ouvrir dans Databricks

Configuration de l'environnement​

Générer des traces pour l'analyse​

Référence rapide​

Exemples de recherche​

Rechercher par statut​

Rechercher par Timestamp​

Rechercher par temps d'exécution​

Recherche par métadonnées​

Rechercher par tags​

Filtres complexes​

Étapes suivantes​

Exemple de Notebook​