Explorar: Buscar e inspeccionar trazas de producción
En esta página
Lección reescrita el 2 de noviembre de 2026 basándose en las páginas Send traces y Explore traces de Mistral y en el SDK
mistralai3.7.0: El Explorador se centra en trazas de OpenTelemetry consultadas mediante un lenguaje de expresiones de búsqueda; el método heredadochat_completion_events.searchya no existe. Fuentes: Send traces · Explore traces.
El Explorador: Tu ventana a la producción
El Explorador de Trazas es el lugar donde buscas, filtras e inspeccionas cada traza que fluye a través de tus aplicaciones de IA. Lo encontrarás en Studio bajo Observability → Traces. Sin embargo, las trazas no aparecerán allí a menos que las actives primero: el rastreo está desactivado por defecto.
Envío de trazas
Con el SDK de Python, instala la extensión de telemetría (mistralai[telemetry], versión 2.4.13 o posterior) y, a continuación, actívala en el 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 de ese momento, el SDK rastrea automáticamente las llamadas a modelos, incrustaciones (embeddings), operaciones de agentes, completados FIM y OCR. Las llamadas a tus propias herramientas no se rastrean de forma predeterminada: debes añadir sus extensiones (spans) utilizando el rastreador del 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
Otras fuentes se comportan de manera diferente: Workflows rastrea cada ejecución tan pronto como se establece OTEL_ENABLED=true en el servicio, mientras que Vibe Work se activa mediante una configuración de administrador en Studio. El SDK de TypeScript ofrece configureTelemetry. Por el contrario, Vibe Code (CLI y Web) y el Playground de Studio no envían trazas. Todas las fuentes eliminan parte de los datos por defecto antes de la exportación; la página Data redaction detalla esta política y cómo ajustarla.
Qué contiene una traza
Una traza es un árbol de extensiones (spans), donde cada extensión representa una operación en la cadena:
| Campo | Contenido |
|---|---|
| Trace ID | Identificador de toda la cadena de ejecución |
| Spans | Operaciones: llamadas a modelos, llamadas a herramientas, pasos de flujo de trabajo |
| Duration | Tiempo de cada extensión y de toda la traza |
| Tokens | Tokens de entrada y salida para cada llamada al modelo |
| Status | Éxito o error, incluido el mensaje de error |
| Source | Producto de origen: SDK, Workflows, Vibe Work |
| Tags | Etiquetas aplicadas por el SDK y metadatos automáticos, como el modelo |
Al hacer clic en una traza se abre su árbol de extensiones; cada extensión se expande para mostrar la entrada, la salida, la latencia y los tokens.
El lenguaje de búsqueda
El Explorador acepta un lenguaje de expresiones: condiciones sobre campos de traza combinadas con AND, OR y NOT.
| Categoría | Operadores | Ejemplo |
|---|---|---|
| Comparación | =, !=, <, <=, >, >= | duration_ns > 5000000000 |
| Patrón | LIKE, ILIKE, NOT LIKE | service_name LIKE '%agent%' |
| Subcadena | CONTAINS, NOT CONTAINS | service_name CONTAINS 'sdk' |
| Expresión regular | REGEXP, NOT REGEXP | service_name REGEXP '^my-' |
| Rango | BETWEEN ... AND ... | duration_ns BETWEEN 1000000 AND 5000000000 |
| Lista | IN (...), NOT IN (...) | status_code IN ('Error', 'Ok') |
| Presencia | EXISTS, NOT EXISTS | error_message EXISTS |
Los campos disponibles incluyen service_name, status_code (Ok o Error), duration_ns (en nanosegundos), error_message, start_time, models_used (una lista) y cualquier atributo de extensión utilizando la sintaxis de corchetes: span_attributes['gen_ai.request.model']. Para listas, has(models_used, 'mistral-medium-latest'), hasany(...) y hasall(...) complementan a CONTAINS.
# Todas las trazas fallidas de un servicio
service_name = 'agent-support' AND status_code = 'Error'
# Trazas de más de 5 segundos
duration_ns > 5000000000
# Trazas que llamaron a un modelo específico
span_attributes['gen_ai.request.model'] CONTAINS 'mistral-large'
Si una búsqueda no devuelve resultados, elimina todas las condiciones excepto el rango de tiempo y vuelve a añadirlas una por una. Un error común es filtrar por status_code = 'Error' cuando la mayoría de las trazas tienen éxito.
Consulta de trazas mediante el SDK
Puedes realizar las mismas búsquedas programáticamente durante un rango de tiempo:
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")
La respuesta utiliza paginación basada en cursores. La referencia de la API documenta los puntos finales (endpoints) Traces y Spans (búsqueda, traza única, campos y valores posibles, extensiones de una traza).
Añadir extensiones a un conjunto de datos
El Explorador también sirve como punto de partida para conjuntos de datos de prueba. Desde una traza, el menú de una extensión ofrece Add span to dataset; en la vista Spans, puedes seleccionar hasta 500 a la vez y mapear cada campo de la extensión a un campo de registro. Esta función está relacionada con las evaluaciones sin conexión (offline), reservadas para organizaciones Enterprise (Lección 15).
Puntos clave
- El rastreo está desactivado por defecto:
configure_telemetry(client)lo activa para el SDK de Python,OTEL_ENABLED=truepara Workflows - Las llamadas a modelos se rastrean automáticamente; las llamadas a herramientas requieren un rastreo manual con
get_telemetry_tracer - El Explorador filtra trazas utilizando un lenguaje de expresiones (
service_name,status_code,duration_ns,span_attributes['…']) - El SDK expone la misma capacidad de búsqueda:
client.beta.observability.traces.search(search_expression=...) - Las extensiones interesantes se convierten en registros de conjunto de datos con un solo clic o en lotes de 500