Explorar: Pesquisar e inspecionar registos de produção
Nesta página
Lição reescrita a 2 de novembro de 2026 com base nas páginas Send traces e Explore traces da Mistral e no SDK
mistralai3.7.0: O Explorador foca-se em registos OpenTelemetry consultados através de uma linguagem de expressões de pesquisa; o método legadochat_completion_events.searchdeixou 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:
| Campo | Conteúdo |
|---|---|
| ID do Registo | Identificador para toda a cadeia de execução |
| Intervalos (Spans) | Operações: chamadas de modelo, chamadas de ferramentas, passos de workflow |
| Duração | Tempo para cada intervalo e para o registo inteiro |
| Tokens | Tokens de entrada e saída para cada chamada de modelo |
| Estado | Sucesso ou erro, incluindo a mensagem de erro |
| Origem | Produto de origem: SDK, Workflows, Vibe Work |
| Etiquetas | Ró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.
| Categoria | Operadores | Exemplo |
|---|---|---|
| Comparação | =, !=, <, <=, >, >= | duration_ns > 5000000000 |
| Padrão | LIKE, ILIKE, NOT LIKE | service_name LIKE '%agent%' |
| Subcadeia | CONTAINS, NOT CONTAINS | service_name CONTAINS 'sdk' |
| Expressão regular | REGEXP, NOT REGEXP | service_name REGEXP '^my-' |
| Intervalo | BETWEEN ... AND ... | duration_ns BETWEEN 1000000 AND 5000000000 |
| Lista | IN (...), NOT IN (...) | status_code IN ('Error', 'Ok') |
| Presença | EXISTS, NOT EXISTS | error_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=truepara 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