Auto-tracing

AstrApp registra en Opik las llamadas a modelos que pasan por la plataforma, sin que instales ni configures nada. Para tu propia aplicación, usas la API de trazas.

¿Qué es el auto-tracing?

Es el registro automático de trazas en el proyecto de Opik de tu organización.

Cuando una función de AstrApp llama a un modelo, guarda la traza con la entrada, la salida y la duración y, en las llamadas al modelo, un span con los tokens usados. No hay SDK que instalar ni código que envolver.

Si el registro en Opik falla, la función sigue: tu modelo responde igual y la traza simplemente no se guarda.

En la app

Esto es lo que se registra solo:

Qué haces	Traza	Span
Chat de la plataforma `POST /api/v1/chat`	`chat-{modelo}` con las etiquetas `chat` y `litellm`	`llm-litellm`, tipo `llm`, con tokens
Inferencia de tu modelo `POST /api/v1/inference/{modelId}/chat`	`inference-{nombre}` con `inference`, `chat` y el proveedor	`llm-{proveedor}`, tipo `llm`, con tokens
Evaluación de un modelo `POST /api/v1/evaluation/{modelId}`	Una `evaluation-{nombre}` por prompt, con sus métricas en la salida	—
Subida de documentos `POST /api/v1/documents`	`document-upload` con el tipo de conocimiento y el resultado	—
Conversaciones que llegan por Kommo	Una por conversación, con `webhook`, `kommo` y `auto-logged`	Uno por turno (`turn-1`, `turn-2`…)

En el chat y la inferencia, las respuestas en streaming llevan además la etiqueta streaming.

API

Para registrar las llamadas de una aplicación que corre fuera de AstrApp.

Crea la traza al terminar la llamada a tu modelo y, con su id, agrégale un span llm con los tokens. Los campos de cada uno están en Trazas y Spans.

registrar-llamada.ts

const base = `https://app.astrapp.lat/api/v1/projects/${process.env.ASTRAPP_PROJECT_ID}/opik`
const headers = {
  Authorization: `Bearer ${process.env.ASTRAPP_API_KEY}`,
  'Content-Type': 'application/json',
}

export async function registrarLlamada(opts: {
  nombre: string
  modelo: string
  mensajes: Array<{ role: string; content: string }>
  respuesta: string
  inicio: Date
  fin: Date
  tokens: { prompt_tokens: number; completion_tokens: number; total_tokens: number }
  metadata?: Record<string, unknown>
}) {
  const traza = await fetch(`${base}/traces`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      name: opts.nombre,
      input: { messages: opts.mensajes },
      output: { content: opts.respuesta, usage: opts.tokens },
      metadata: { model: opts.modelo, ...opts.metadata },
      tags: ['mi-app'],
      startTime: opts.inicio.toISOString(),
      endTime: opts.fin.toISOString(),
    }),
  }).then((r) => r.json())

  await fetch(`${base}/spans`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      trace_id: traza.data.id,
      name: 'llamada-al-modelo',
      type: 'llm',
      model: opts.modelo,
      input: { messages: opts.mensajes },
      output: { content: opts.respuesta },
      usage: opts.tokens,
      start_time: opts.inicio.toISOString(),
      end_time: opts.fin.toISOString(),
    }),
  })
}

Límites y notas

La ingesta de trazas acepta hasta 500 peticiones por minuto (ver Trazas).
Las trazas automáticas del chat guardan tu id de usuario en metadata.user_id.

Metadatos que conviene registrar

conversation_id y un id de usuario, para seguir una conversación de punta a punta.
model, para que la traza muestre qué versión respondió.
El canal o el tipo de consulta, para filtrar y comparar después.

Nunca registres datos sensibles

No mandes contraseñas, API keys, números de tarjeta ni datos personales en input, output o metadata. Usa identificadores internos en su lugar.