Conceitos de rastreamento

O rastreamento é uma técnica de observabilidade que captura todo o fluxo de execução de uma solicitação em sua aplicação. Ao contrário do registro tradicional, que armazena eventos isolados, o rastreamento cria um mapa detalhado de como os dados fluem pelos seus sistemas e registra todas as operações ao longo do processo.

Fluxo de trabalho complexo e de várias etapas de execução de aplicativos GenAI que combina vários componentes, como LLMs, recuperadores, ferramentas e agentes. O rastreamento torna esses fluxos de trabalho depuráveis, capturando todo o fluxo de execução.

Estrutura do traço

Um rastreamento do MLflow compreende dois objetos principais:

1. Trace.info do tipo TraceInfo: Metadados que descrevem a origem, o estado e o tempo de execução do rastreamento. TraceInfo também contém tags. As tags são pares de key-valor fornecidos pelo usuário, pela sessão e pelo desenvolvedor, que você pode usar para pesquisar ou filtrar rastreamentos.

2. Trace.data do tipo TraceData: A carga útil real contendo objetos Span instrumentados que capturam a execução passo a passo do seu aplicativo, da entrada à saída.

Os rastreamentos MLflow são compatíveis com as especificações do OpenTelemetry, um padrão da indústria amplamente adotado para observabilidade. Os rastreamentos permanecem interoperáveis com outras ferramentas de observabilidade compatíveis com OpenTelemetry, enquanto o MLflow estende o modelo OpenTelemetry com estruturas e atributos específicos do GenAI.

Informações de rastreamento

TraceInfo fornece metadados leves sobre o rastreamento geral. Os principais campos incluem:

campo	Descrição
trace_id	Identificador único para o rastreamento
trace_location	Onde o rastreamento é armazenado (Experimento MLflow ou Tabela de Inferência Databricks)
request_time	Início do rastreamento em milissegundos
state	Status do rastreamento: OK, ERROR, IN_PROGRESS, ou STATE_UNSPECIFIED
execution_duration	duração do trace em milissegundos
request_preview	Pré-visualização codificada em JSON da entrada (entrada raiz do span)
response_preview	Pré-visualização da saída codificada em JSON (saída do intervalo raiz)
tags	par chave-valor para filtrar e pesquisar rastros

Dados de rastreamento

O objeto TraceData é um contêiner de objetos Span onde os detalhes de execução são armazenados. Cada período captura informações sobre uma operação específica, incluindo:

• Pedidos e respostas
• Medições de latência
• Mensagens LLM e parâmetros da ferramenta
• Documentos recuperados e contexto
• Metadados e atributos

Os Spans formam uma estrutura hierárquica por meio de conexões pai-filho, criando uma árvore que representa o fluxo de execução do seu aplicativo.

tags

As tags são pares key-valor mutáveis associados aos rastreamentos para organização e filtragem. O MLflow define tags padrão para casos de uso comuns:

• mlflow.trace.sessionIdentificador de sessão para agrupar rastreamentos relacionados
• mlflow.trace.user: Identificador do usuário para acompanhamento de interações por usuário
• mlflow.source.namePonto de entrada ou script que gerou o rastreamento.
• mlflow.source.git.commit: Hash do commit do Git do código-fonte (se aplicável)
• mlflow.source.type: Tipo de origem (PROJECT, NOTEBOOK, etc.)

Você também pode adicionar tags personalizadas para suas necessidades específicas. Saiba mais em Adicionar contexto aos rastreamentos e Anexar tags/metadados personalizados.

Armazenamento

O MLflow otimiza o armazenamento de rastreamento para melhor desempenho e custo. Para personalizar o local de armazenamento, anexe um volume Unity Catalog ao criar um experimento. O acesso é então regido pelos privilégios de volumeUnity Catalog.

TraceInfo é armazenado diretamente em um banco de dados relacional como linhas indexadas, o que permite consultas rápidas para busca e filtragem de registros.

TraceData (Os intervalos) são armazenados no armazenamento de artefatos em vez do banco de dados relacional porque os intervalos são maiores. Isso mantém as consultas rápidas mesmo quando o volume de rastreamento aumenta.

Traços ativos vs. traços finalizados

Um rastreamento ativo é um rastreamento que o MLflow está escrevendo no momento, por exemplo, enquanto uma função decorada com @mlflow.trace está em execução. Após a função decorada ser finalizada, o rastreamento termina, mas você ainda pode anotá-lo com novos dados.

Para trabalhar com rastros ativos ou recentes, utilize estes métodos:

• mlflow.get_active_trace_id(): retorna o ID do rastreamento atualmente ativo.
• mlflow.get_last_active_trace_id(): retorna o ID do rastreamento finalizado mais recente.

Próximas etapas

• Conceitos de span — Aprenda sobre spans e como eles representam operações individuais.
• Comece agora: MLflow Tracing para GenAI ( Notebook Databricks ) — Obtenha experiência prática com rastreamento em um Notebook.