Tutorial: Pesquisar rastros programaticamente
Este tutorial fornece exemplos simples para começar a usar mlflow.search_traces(). Para obter detalhes sobre como pesquisar rastreamentos, consulte Pesquisar rastreamentos programaticamente.
Configuração do ambiente
Instale o pacote necessário:
mlflow[databricks]Use a versão mais recente do MLflow para obter mais recursos e melhorias.openaiEste aplicativo usará o cliente da API OpenAI para acessar modelos hospedados no Databricks.
%pip install -qq --upgrade "mlflow[databricks]>=3.1.0" openai
dbutils.library.restartPython()
Crie um experimento no MLflow. Se você estiver usando um Notebook Databricks , pode pular esta etapa e usar o experimento default do Notebook. Caso contrário, siga o guia de início rápido de configuração do ambiente para criar o experimento e conectar-se ao servidor MLflow Acompanhamento.
Gere rastros para análise.
Este aplicativo simples gera rastreamentos para usar com search_traces().
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
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?")
Referência rápida
# 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() Retorna um DataFrame Pandas ou uma lista de Trace objetos com estes campos:
list(traces.columns)
['trace_id',
'trace',
'client_request_id',
'state',
'request_time',
'execution_duration',
'request',
'response',
'trace_metadata',
'tags',
'spans',
'assessments']
Exemplos de pesquisa
Ao executar este tutorial, as células de código abaixo exibirão os resultados da pesquisa.
Pesquisar por status
A busca por status permite encontrar registros de sucesso, falha ou em andamento.
mlflow.search_traces(filter_string="attributes.status = 'OK'")
mlflow.search_traces(filter_string="attributes.status != 'ERROR'")
Pesquisar por data e hora
O tempo deve ser especificado em milissegundos, usando timestamps Unix.
Encontre os registros recentes dos últimos 5 minutos:
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}"
)
Pesquisar em um intervalo de datas:
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}"
)
Você também pode usar o alias 'timestamp' em vez de 'timestamp_ms':
mlflow.search_traces(filter_string=f"attributes.timestamp > {five_minutes_ago}")
Pesquisar por tempo de execução
Encontre rastros lentos:
mlflow.search_traces(filter_string="attributes.execution_time_ms > 2500")
Você também pode usar o alias 'latency' em vez de 'execution_time_ms':
mlflow.search_traces(filter_string="attributes.latency > 1000")
Pesquisar por metadados
Lembre-se de usar crases (`) para nomes de metadados que contenham pontos.
Pesquisar metadados personalizados para um usuário específico:
mlflow.search_traces(filter_string="metadata.`mlflow.trace.user` = 'name@my_company.com'")
Pesquisar por tags
Lembre-se de usar crases (`) para nomes tag com pontos.
tags do sistema de pesquisa:
mlflow.search_traces(
filter_string="tags.`mlflow.traceName` = 'my_app'"
)
Pesquisar conjunto de tags personalizadas usando mlflow.update_current_trace():
mlflow.search_traces(filter_string="tags.environment = 'production'")
Filtros complexos
Apenas o método AND é suportado, não o OR.
Encontre exemplos recentes de produção bem-sucedida:
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'"
)
Encontre rapidamente rastros de um usuário específico:
mlflow.search_traces(
filter_string="attributes.execution_time_ms < 2500 AND "
"metadata.`mlflow.trace.user` = 'name@my_company.com'"
)
Encontre registros de uma função específica que excedam um limite de desempenho:
mlflow.search_traces(
filter_string="tags.`mlflow.traceName` = 'my_app' AND "
"attributes.execution_time_ms > 1000"
)
Próximos passos
Em geral, você chamará mlflow.search_traces() para extrair um conjunto de rastros e, em seguida, realizar análises ou processamentos adicionais do DataFrame ou lista de objetos Trace retornados.
Para exemplos mais avançados, veja:
- Tutorial: Rastrear e analisar usuários e ambientes - execução de um exemplo de adição de metadados de contexto a rastreamentos e análise dos resultados.
- Exemplos: análise de rastreamento - Veja uma variedade de exemplos de análise de rastreamento