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: um local de rastreamento do Unity Catalog (recomendado), um experimento MLflow ou uma tabela de inferência do 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

campo	Descrição
trace_id	Identificador único para o rastreamento
trace_location	Onde o rastreamento é armazenado: um local de rastreamento do Unity Catalog (recomendado), um experimento MLflow ou uma tabela de inferência do 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

Um rastreamento sempre pertence a um experimento MLflow, mas você escolhe o back-end que armazena fisicamente os dados do rastreamento:

• **Tabelas Delta OTel do Unity Catalog (recomendado)**: Para escala e governança, aponte seu experimento para um local de rastreamento do Unity Catalog. Rastreamentos são armazenados em tabelas Delta no formato OpenTelemetry, sem limite por experimento, governados pelas permissões do Unity Catalog e consultáveis com SQL. Consulte Armazenar rastreamentos OpenTelemetry no Unity Catalog.
• Back-end de experimento gerenciado : O default quando nenhuma localização de rastreamento do Unity Catalog está configurada. TraceInfo é armazenado em um banco de dados relacional como linhas indexadas, o que permite queries rápidas para pesquisa e filtragem de rastreamentos. TraceData (os intervalos) é armazenado no armazenamento de artefatos em vez do banco de dados relacional porque os intervalos são maiores. Isso mantém as queries 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.

Recursos adicionais

• Conceitos de intervalo — Saiba mais sobre intervalos e como eles capturam operações individuais.
• Começar: MLflow Tracing para GenAI (Databricks Notebook) — Obtenha experiência prática com o rastreamento em um Notebook.