Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Explorar: Pesquisar e inspecionar registos de produção

Aula 12 de 16 Atualizada a 2 de novembro de 2026 Avancado
Nesta página
  1. O Explorador: A sua janela para a produção
  2. Envio de registos
  3. O que contém um registo
  4. A linguagem de pesquisa
  5. Consulta de registos via SDK
  6. Adicionar intervalos a um conjunto de dados
  7. Pontos-chave

Lição reescrita a 2 de novembro de 2026 com base nas páginas Send traces e Explore traces da Mistral e no SDK mistralai 3.7.0: O Explorador foca-se em registos OpenTelemetry consultados através de uma linguagem de expressões de pesquisa; o método legado chat_completion_events.search deixou de existir. Fontes: Send traces · Explore traces.

O Explorador: A sua janela para a produção

O Explorador de Registos (Trace Explorer) é onde pesquisa, filtra e inspeciona todos os registos que fluem através das suas aplicações de IA. Encontrá-lo-á no Studio sob Observabilidade → Registos. No entanto, os registos não aparecerão aí a menos que os ative primeiro: o registo está desativado por predefinição.

Envio de registos

Com o SDK Python, instale a extensão de telemetria (mistralai[telemetry], versão 2.4.13 ou posterior) e, em seguida, ative-a no cliente:

from mistralai.client import Mistral
from mistralai.extra.observability import configure_telemetry

client = Mistral(api_key="your-api-key")
configure_telemetry(client)

A partir desse momento, o SDK regista automaticamente chamadas de modelos, incorporações (embeddings), operações de agentes, conclusões FIM e OCR. As chamadas às suas próprias ferramentas não são registadas nativamente: deve adicionar os seus intervalos (spans) utilizando o rastreador do SDK.

from mistralai.extra.observability import get_telemetry_tracer

tracer = get_telemetry_tracer(client, "agent-support")

with tracer.start_as_current_span("invoke_agent"):
    response = client.chat.complete(
        model="mistral-small-latest",
        messages=[{"role": "user", "content": "What is the status of order 4521?"}],
    )
    with tracer.start_as_current_span("execute_tool order_tracking") as span_tool:
        span_tool.set_attribute("gen_ai.tool.name", "order_tracking")
        span_tool.set_attribute("gen_ai.tool.call.arguments", "4521")
        # call your tool here

Outras fontes comportam-se de forma diferente: os Workflows registam cada execução assim que OTEL_ENABLED=true é definido no serviço, enquanto o Vibe Work é ativado através de uma definição de administrador no Studio. O SDK TypeScript oferece configureTelemetry. Por outro lado, o Vibe Code (CLI e Web) e o Playground do Studio não enviam registos. Todas as fontes omitem parte dos dados por predefinição antes da exportação; a página Data redaction detalha esta política e como ajustá-la.

O que contém um registo

Um registo é uma árvore de intervalos (spans), onde cada intervalo representa uma operação na cadeia:

CampoConteúdo
ID do RegistoIdentificador para toda a cadeia de execução
Intervalos (Spans)Operações: chamadas de modelo, chamadas de ferramentas, passos de workflow
DuraçãoTempo para cada intervalo e para o registo inteiro
TokensTokens de entrada e saída para cada chamada de modelo
EstadoSucesso ou erro, incluindo a mensagem de erro
OrigemProduto de origem: SDK, Workflows, Vibe Work
EtiquetasRótulos aplicados pelo SDK e metadados automáticos, como o modelo

Ao clicar num registo, abre-se a sua árvore de intervalos; cada intervalo expande-se para mostrar entrada, saída, latência e tokens.

A linguagem de pesquisa

O Explorador aceita uma linguagem de expressões: condições sobre campos de registos combinadas com AND, OR e NOT.

CategoriaOperadoresExemplo
Comparação=, !=, <, <=, >, >=duration_ns > 5000000000
PadrãoLIKE, ILIKE, NOT LIKEservice_name LIKE '%agent%'
SubcadeiaCONTAINS, NOT CONTAINSservice_name CONTAINS 'sdk'
Expressão regularREGEXP, NOT REGEXPservice_name REGEXP '^my-'
IntervaloBETWEEN ... AND ...duration_ns BETWEEN 1000000 AND 5000000000
ListaIN (...), NOT IN (...)status_code IN ('Error', 'Ok')
PresençaEXISTS, NOT EXISTSerror_message EXISTS

Os campos disponíveis incluem service_name, status_code (Ok ou Error), duration_ns (em nanossegundos), error_message, start_time, models_used (uma lista) e qualquer atributo de intervalo usando a sintaxe de colchetes: span_attributes['gen_ai.request.model']. Para listas, has(models_used, 'mistral-medium-latest'), hasany(...) e hasall(...) complementam o CONTAINS.

# Todos os registos com falha de um serviço
service_name = 'agent-support' AND status_code = 'Error'

# Registos com duração superior a 5 segundos
duration_ns > 5000000000

# Registos que chamaram um modelo específico
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'

Se uma pesquisa não devolver resultados, remova todas as condições exceto o intervalo de tempo e volte a adicioná-las uma a uma. Um erro comum é filtrar por status_code = 'Error' quando a maioria dos registos é bem-sucedida.

Consulta de registos via SDK

Pode realizar as mesmas pesquisas programaticamente num intervalo de tempo:

from datetime import datetime, timedelta, timezone

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")
now = datetime.now(timezone.utc)

response = client.beta.observability.traces.search(
    from_=now - timedelta(days=1),
    to=now,
    search_expression="service_name = 'agent-support' AND status_code = 'Error'",
    page_size=50,
)

for trace in response.traces.results or []:
    print(f"{trace.trace_id} {trace.root_span_name} : {trace.duration_ns / 1e9:.1f} s")

A resposta utiliza paginação baseada em cursor. A referência da API documenta os endpoints Traces e Spans (pesquisa, registo único, campos e valores possíveis, intervalos de um registo).

Adicionar intervalos a um conjunto de dados

O Explorador serve também como ponto de partida para conjuntos de dados de teste. A partir de um registo, o menu de um intervalo oferece Add span to dataset; na vista Spans, pode selecionar até 500 de uma vez e mapear cada campo do intervalo para um campo de registo. Esta função relaciona-se com avaliações offline, reservadas a organizações Enterprise (Lição 15).

Pontos-chave

  • O registo está desativado por predefinição: configure_telemetry(client) ativa-o para o SDK Python, OTEL_ENABLED=true para Workflows
  • As chamadas de modelo são registadas automaticamente; as chamadas de ferramentas exigem registo manual com get_telemetry_tracer
  • O Explorador filtra registos usando uma linguagem de expressões (service_name, status_code, duration_ns, span_attributes['…'])
  • O SDK expõe a mesma capacidade de pesquisa: client.beta.observability.traces.search(search_expression=...)
  • Intervalos interessantes tornam-se registos de conjunto de dados num único clique ou em lotes de 500