メインコンテンツまでスキップ
に最終更新

チュートリアル: プログラムでトレースを検索する

このチュートリアルでは、 mlflow.search_traces()を使い始めるための簡単な例を示します。トレースの検索の詳細については、 「プログラムによるトレースの検索」を参照してください。

環境設定​

必要なパッケージをインストールします。

  • mlflow[databricks]: より多くの機能と改善を得るには、最新バージョンの MLflow を使用してください。
  • openai: このアプリは、OpenAI API クライアントを使用して、Databricks でホストされるモデルを呼び出します。
Python
%pip install -qq --upgrade "mlflow[databricks]>=3.1.0" openai
dbutils.library.restartPython()

MLflowエクスペリメントを作成します。 Databricksノートブックを使用している場合は、このステップをスキップして、デフォルトのノートブック体験を使用できます。 それ以外の場合は、環境設定のクイックスタートに従ってエクスペリメントを作成し、 MLflowトラッキング サーバーに接続します。

分析用のトレースを生成する​

このシンプルなアプリは、 search_traces()で使用するトレースを生成します。

Python

import mlflow
from databricks.sdk import WorkspaceClient

mlflow.openai.autolog()

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

    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={
            "mlflow.trace.user": 'name@my_company.com',
        },
        tags={
            "environment": "production",
        },
    )

    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?")

クイックリファレンス​

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

# Search by time
mlflow.search_traces(filter_string="attributes.timestamp_ms > 1749006880539")
mlflow.search_traces(filter_string="attributes.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="tags.environment = 'production'")
mlflow.search_traces(filter_string="tags.`mlflow.traceName` = 'my_app'")

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

traces = mlflow.search_traces()
traces

mlflow.search_traces() 次のフィールドを持つPandas DataFrameまたはTraceオブジェクトのリストを返します。

Python
list(traces.columns)
Output
['trace_id',
 'trace',
 'client_request_id',
 'state',
 'request_time',
 'execution_duration',
 'request',
 'response',
 'trace_metadata',
 'tags',
 'spans',
 'assessments']

検索例​

このチュートリアルを実行すると、以下のコード セルに検索結果が表示されます。

ステータスで検索​

ステータスで検索すると、成功したトレース、失敗したトレース、進行中のトレースを見つけることができます。

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

タイムスタンプで検索​

時間は、Unix タイムスタンプを使用してミリ秒単位で指定する必要があります。

過去 5 分間の最新のトレースを検索します。

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"attributes.timestamp_ms > {five_minutes_ago}"
)

日付範囲で検索:

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"attributes.timestamp_ms > {start_date} AND attributes.timestamp_ms < {end_date}"
)

'timestamp_ms' の代わりに 'timestamp' エイリアスを使用することもできます。

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

実行時間で検索​

遅いトレースを探す:

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

'execution_time_ms' の代わりに 'latency' エイリアスを使用することもできます。

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

メタデータで検索​

ドットを含むメタデータ名には必ずバッククォートを使用してください。

特定のユーザーのカスタム メタデータを検索します。

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

タグで検索​

ドットを含むタグ名には必ずバッククォートを使用してください。

検索システムタグ:

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

mlflow.update_current_trace()を使用して設定されたカスタムタグを検索します:

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

複雑なフィルター​

OR ではなく AND のみがサポートされます。

最近成功した本番運用トレースを見つけます。

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

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

特定のユーザーからの高速トレースを検索します。

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

パフォーマンスしきい値を超える特定の関数からのトレースを検索します。

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

次のステップ​

一般的には、 mlflow.search_traces()を呼び出してトレースのセットを抽出し、返された DataFrame またはTraceオブジェクトのリストに対してさらに分析または処理を実行します。

より高度な例については、以下を参照してください。

サンプルノートブック​

チュートリアル: プログラムでトレースを検索する

Open notebook in new tab