Tutorial: Rastrear e analisar usuários e ambientes

Este tutorial demonstra como adicionar contexto aos rastreamentos para monitorar e analisar usuários, sessões e implantações.

• Em um aplicativo de bate-papo simples, você usará mlflow.update_current_trace() para adicionar metadados e tags personalizados aos rastreamentos.
• Para analisar os rastros, você usará mlflow.search_traces() para extrair os rastros relevantes e compute estatísticas para usuários, sessões, ambientes e versões de aplicativos.

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.

Python

%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.

Defina e acompanhe o andamento da sua aplicação.

O aplicativo de bate-papo simples abaixo utiliza um modelo de base hospedado no Databricks para responder às consultas do usuário.

O rastreamento é feito usando:

• mlflow.openai.autolog() para registrar automaticamente chamadas do cliente OpenAI
• @mlflow.trace para rastrear a lógica do aplicativo em my_app()
• mlflow.update_current_trace() para adicionar contexto aos rastreamentos dentro de my_app():
  • Contexto do usuário e da sessão: informações específicas da consulta, como IDs de usuário, podem ser passadas para a lógica do aplicativo como argumentos.
  • Contexto de implantação: Informações específicas da implantação, como o ambiente ou a versão do aplicativo, são passadas para o aplicativo por meio de variáveis de ambiente, o que simplifica as alterações de configuração entre as implantações.

MLflow preenche automaticamente alguns metadados nos rastreamentos, mas você pode substituir os valores default . Você também pode definir metadados personalizados. O exemplo abaixo demonstra ambos.

Python

import mlflow
import os
from databricks.sdk import WorkspaceClient

mlflow.openai.autolog()

@mlflow.trace
def my_app(user_id: str, session_id: str, message: str) -> str:
    """Process a chat message with extra content logging for traces."""

    # Add user and session context to the current trace.
    # The @mlflow.trace decorator ensures there is an active trace.
    mlflow.update_current_trace(
        metadata={
            "mlflow.trace.user": user_id,
            "mlflow.trace.session": session_id,
        },
        tags={
          "query_category": "chat",  # Example of a custom tag
        },
    )

    app_environment = os.getenv("APP_ENVIRONMENT", "development")
    mlflow.update_current_trace(
        metadata={
            # Override automatically populated metadata
            "mlflow.source.type": app_environment,  # Override default LOCAL/NOTEBOOK
            # Add custom metadata
            "app_version": os.getenv("APP_VERSION", "1.0.0"),
            "deployment_id": os.getenv("DEPLOYMENT_ID", "unknown"),
        }
    )

    # The trace will capture the execution time, inputs, outputs, and any errors
    # Your chat logic here
    response = chat_completion(message)
    return response


# Basic chat logic
def chat_completion(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,
            },
        ]
    )
    return response.choices[0].message.content

A lógica do aplicativo acima recebe o usuário, a sessão e outros metadados como argumentos da função. Em uma aplicação de produção, a implementação pode extrair metadados dos cabeçalhos de um objeto de requisição. Por exemplo, se o aplicativo for implantado como um aplicativo Databricks, ele poderá acessar cabeçalhos HTTP com metadados.

Em seguida, simule alguns usuários e sessões diferentes, cada um com uma ou mais interações de bate-papo. Defina informações de implantação usando variável de ambiente.

Python

# Set environment variables to log deployment-specific metadata with traces.
os.environ["APP_ENVIRONMENT"] = "staging"
os.environ["APP_VERSION"] = "1.0.0"
os.environ["DEPLOYMENT_ID"] = "deployment-123"

# Run the chat completion with user and session context to generate example traces:
for session in range(2):
  # 2 chat interactions per session for this user
  result = my_app(
      user_id="user-123",
      session_id=f"session-abc-{session}",
      message="What is MLflow and how does it help with GenAI?"
  )
  result = my_app(
      user_id="user-123",
      session_id=f"session-abc-{session}",
      message="What is ML vs. AI?"
  )

os.environ["APP_VERSION"] = "1.1.0"
os.environ["DEPLOYMENT_ID"] = "deployment-456"

for session in range(2):
  # 1 chat interaction per session for this user
  result = my_app(
      user_id="user-456",
      session_id=f"session-def-{session}",
      message="What is MLflow and how does it help with machine learning?"
  )

Rastros de pesquisa

Todas as análises abaixo são baseadas no uso de mlflow.search_traces() para coletar traços relevantes para análise:

Python

import mlflow
traces = mlflow.search_traces()
traces

Cada rastreamento é anotado com o contexto adicional registrado no aplicativo, como IDs de usuário:

Python

first_trace = traces.iloc[0]
first_trace.trace_metadata['mlflow.trace.user']

Output

'user-456'

Analisar o comportamento do usuário

Primeiro, analise o comportamento de um usuário específico.

Python

import pandas as pd
import time

def analyze_user_behavior(user_id: str, days: int = 7):
    """Analyze activity patterns for a specific user."""

    cutoff_ms = int((time.time() - days * 86400) * 1000)

    traces = mlflow.search_traces(
        filter_string=f"metadata.`mlflow.trace.user` = '{user_id}' AND "
                      f"trace.timestamp_ms > {cutoff_ms}",
        order_by=["trace.timestamp_ms DESC"],
    )

    if len(traces) == 0:
        print(f"No activity found for user {user_id}")
        return

    # Calculate key metrics
    total_interactions = len(traces)
    unique_sessions = set(row.trace_metadata.get("mlflow.trace.session", "") for index, row in traces.iterrows())
    unique_sessions.discard("")

    print(f"User {user_id} Activity Report ({days} days)")
    print("=" * 50)
    print(f"Total interactions: {total_interactions}")
    print(f"Unique sessions: {len(unique_sessions)}")

    # Daily activity
    traces['date'] = pd.to_datetime(traces['request_time'], unit='ms').dt.date
    daily_activity = traces.groupby('date').size()
    print(f"\nDaily activity:")
    print(daily_activity.to_string())

    # Query categories
    query_categories = traces['tags'].apply(lambda tags: tags.get('query_category'))
    unique_categories = set(query_categories.dropna())
    category_counts = query_categories.value_counts()
    print(f"\nQuery categories:")
    print(category_counts.to_string())

    # Performance stats
    print(f"\nPerformance:")
    print(f"Average response time: {traces['execution_duration'].mean():.1f}ms")
    print(f"Error rate: {(traces['state'] == 'ERROR').mean() * 100:.1f}%")

    return traces

Python

analyze_user_behavior(user_id="user-123")

Output

User user-123 Activity Report (7 days)
==================================================
Total interactions: 4
Unique sessions: 2

Daily activity:
date
2025-12-12    4

Query categories:
tags
chat    4

Performance:
Average response time: 2177.5ms
Error rate: 0.0%

Analisar o fluxo da sessão

Um usuário pode interagir com seu aplicativo em conversas com múltiplas interações. Analisar a sessão passo a passo pode ajudar a ilustrar a experiência do usuário. Abaixo, os turnos da conversa são colocados em ordem usando registros de tempo.

Python

def analyze_session_flow(session_id: str):
    """Analyze conversation flow within a session."""

    # Get all traces from a session, ordered chronologically
    session_traces = mlflow.search_traces(
        filter_string=f"metadata.`mlflow.trace.session` = '{session_id}'",
        order_by=["timestamp ASC"]
    )

    # Build a timeline of the conversation
    conversation_turns = []
    for index, row in session_traces.iterrows():
        conversation_turns.append({
            "turn": index + 1,
            "timestamp": int(row.request_time),
            "duration_ms": int(row.execution_duration),
            "status": str(row.state),
            "response": row.response,
        })

    return conversation_turns

Python

analyze_session_flow(session_id="session-abc-0")

Output

[{'turn': 1,
  'timestamp': 1765560306051,
  'duration_ms': 2570,
  'status': 'OK',
  'response': 'MLflow is an open-source platform for managing the machine learning lifecycle, including experiment tracking, model packaging, and deployment. For GenAI, it helps by providing tools to track experiments with large language models, manage model versions, log prompts and responses, and deploy AI models at scale while maintaining reproducibility and governance.'},
 {'turn': 2,
  'timestamp': 1765560308943,
  'duration_ms': 2644,
  'status': 'OK',
  'response': 'AI (Artificial Intelligence) is the broader field focused on creating machines that can perform tasks requiring human-like intelligence, while ML (Machine Learning) is a subset of AI that specifically uses algorithms to learn patterns from data without being explicitly programmed for each task. Think of AI as the goal and ML as one of the main methods to achieve it.'}]

Analisar ambientes e versões

Metadados de implantação, como ambiente ou versão do aplicativo, podem ser analisados de forma semelhante a usuários e sessões. Analisar as implementações pode ajudar a monitorar melhorias ou degradações na qualidade, latência ou outras métricas importantes à medida que você itera em seu aplicativo.

Python

traces = mlflow.search_traces()

traces['app_version'] = traces['trace_metadata'].apply(lambda meta: meta.get('app_version'))
traces['user_id'] = traces['trace_metadata'].apply(lambda meta: meta.get('mlflow.trace.user'))
traces['app_environment'] = traces['trace_metadata'].apply(lambda meta: meta.get('mlflow.source.type'))

interactions_per_version = traces.groupby('app_version').size()
print(f"Interactions per app version:")
print(interactions_per_version.to_string())

users_per_version = traces.groupby('app_version')['user_id'].nunique()
print(f"\nDistinct users per app version:")
print(users_per_version.to_string())

interactions_per_environment = traces.groupby('app_environment').size()
print(f"\nInteractions per app environment:")
print(interactions_per_environment.to_string())

Output

Interactions per app version:
app_version
1.0.0    4
1.1.0    4

Distinct users per app version:
app_version
1.0.0    1
1.1.0    1

Interactions per app environment:
app_environment
staging    8

Próximos passos

• Adicione contexto aos rastreamentos - Saiba mais sobre como adicionar metadados e tags personalizados aos rastreamentos.
• Pesquise rastros programaticamente - Saiba mais sobre como usar mlflow.search_traces().
• Analisar vestígios - Veja outros exemplos de análise de vestígios.

Exemplo de caderno

Tutorial: Rastrear e analisar usuários e ambientes

Open notebook in new tab