Ir al contenido principal
Español— Elegir un idioma
Menú

Explorar: Buscar e inspeccionar trazas de producción

Lección 12 de 16 Actualizado el 2 de noviembre de 2026 Avanzado
En esta página
  1. El Explorador: Tu ventana a la producción
  2. Envío de trazas
  3. Qué contiene una traza
  4. El lenguaje de búsqueda
  5. Consulta de trazas mediante el SDK
  6. Añadir extensiones a un conjunto de datos
  7. Puntos clave

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 mistralai 3.7.0: El Explorador se centra en trazas de OpenTelemetry consultadas mediante un lenguaje de expresiones de búsqueda; el método heredado chat_completion_events.search ya 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:

CampoContenido
Trace IDIdentificador de toda la cadena de ejecución
SpansOperaciones: llamadas a modelos, llamadas a herramientas, pasos de flujo de trabajo
DurationTiempo de cada extensión y de toda la traza
TokensTokens de entrada y salida para cada llamada al modelo
StatusÉxito o error, incluido el mensaje de error
SourceProducto de origen: SDK, Workflows, Vibe Work
TagsEtiquetas 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íaOperadoresEjemplo
Comparación=, !=, <, <=, >, >=duration_ns > 5000000000
PatrónLIKE, ILIKE, NOT LIKEservice_name LIKE '%agent%'
SubcadenaCONTAINS, NOT CONTAINSservice_name CONTAINS 'sdk'
Expresión regularREGEXP, NOT REGEXPservice_name REGEXP '^my-'
RangoBETWEEN ... AND ...duration_ns BETWEEN 1000000 AND 5000000000
ListaIN (...), NOT IN (...)status_code IN ('Error', 'Ok')
PresenciaEXISTS, NOT EXISTSerror_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=true para 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