La Guia Completa de Observabilidad IA

Por que los sistemas IA necesitan una observabilidad diferente

Aqui esta el tema con los sistemas IA: el monitoreo tradicional no es suficiente. Cuando tu API REST devuelve un error 500, sabes que algo se rompio. Cuando tu IA devuelve informacion incorrecta con total confianza, tecnicamente todo parece normal. Dashboards verdes, latencia saludable, respuestas HTTP exitosas. Pero tus usuarios estan recibiendo tonterias.

Aprendimos esto de la manera dificil. Uno de nuestros clientes tenia un agente de soporte al cliente que empezo a recomendar productos de la competencia. Ningun error en los logs. Sin picos de latencia. Solo dando consejos terribles silenciosamente durante tres dias antes de que alguien lo notara. Ahi fue cuando nos dimos cuenta: observar la IA no es verificar si esta funcionando. Es verificar si realmente esta trabajando bien.

El monitoreo tradicional te dice si tu sistema esta vivo. La observabilidad IA te dice si tu sistema esta cuerdo.

Esta guia cubre todo lo que hemos aprendido sobre mantener los sistemas IA observables. No teoria - practicas reales que usamos en produccion cada dia.

Los cuatro pilares de la observabilidad IA

Vamos a desglosar lo que realmente necesitas trackear:

La mayoria de equipos empiezan con logging, se dan cuenta de que necesitan metricas para control de costes, anaden trazado cuando el debugging se vuelve doloroso, y finalmente implementan monitoreo de calidad despues de un mal incidente. Ahorrate los problemas y construye los cuatro desde el principio.

Logging: Tu primera linea de defensa

Que loggear

Cada interaccion IA deberia capturar:

const aiCallLog = {
  // Identidad
  requestId: "uuid-v4",
  sessionId: "user-session-id",
  userId: "identificador-usuario-opcional",

  // Input
  prompt: {
    system: "Eres un asistente util...",
    user: "Cual es la politica de devolucion?",
    context: ["doc_recuperado_1", "doc_recuperado_2"]
  },

  // Configuracion del modelo
  model: "gpt-4-turbo",
  temperature: 0.7,
  maxTokens: 1000,

  // Output
  response: {
    content: "Nuestra politica de devolucion permite...",
    finishReason: "stop",
    toolCalls: []
  },

  // Rendimiento
  latencyMs: 2340,
  inputTokens: 456,
  outputTokens: 234,
  totalTokens: 690,

  // Coste
  estimatedCostUsd: 0.0138,

  // Metadatos
  timestamp: "2025-10-15T14:30:00Z",
  environment: "production",
  version: "1.2.3"
};

Implementacion de logging estructurado

No tires simplemente strings a stdout. Estructura tus logs para poder consultarlos realmente:

interface AILogEntry {
  level: 'debug' | 'info' | 'warn' | 'error';
  event: string;
  requestId: string;
  data: {
    model: string;
    promptHash: string;  // Para agrupar prompts similares
    inputTokens: number;
    outputTokens: number;
    latencyMs: number;
    success: boolean;
    errorType?: string;
  };
  context?: {
    userId?: string;
    feature?: string;
    experimentId?: string;
  };
}

function logAICall(entry: AILogEntry) {
  // Enviar a tu infraestructura de logging
  // Usamos una combinacion de logs JSON estructurados + metricas time-series
  console.log(JSON.stringify({
    ...entry,
    timestamp: new Date().toISOString(),
    service: 'ai-gateway'
  }));
}

Loggear datos sensibles

Aqui es donde se pone complicado. Necesitas loggear prompts para debugging, pero los prompts a menudo contienen datos de usuario. Nuestro enfoque:

1. Hashear campos sensibles - Almacena un hash de PII, no los valores reales
2. Almacenamiento separado - Los prompts completos van a un almacen restringido y cifrado con retencion corta
3. Muestreo - Solo loggea prompts completos para un porcentaje de requests en produccion
4. Redaccion - Usa patrones regex para eliminar patrones PII comunes antes de loggear

const sensitivePatterns = [
  /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,  // Email
  /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g,  // Telefono
  /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,  // Tarjeta de credito
];

function redactPII(text: string): string {
  let redacted = text;
  sensitivePatterns.forEach(pattern => {
    redacted = redacted.replace(pattern, '[REDACTADO]');
  });
  return redacted;
}

Metricas: Numeros que realmente importan

Metricas clave a trackear

Configurando la recoleccion de metricas

Asi es como instrumentamos nuestro gateway IA:

import { Counter, Histogram, Gauge } from 'prom-client';

const aiLatency = new Histogram({
  name: 'ai_request_latency_ms',
  help: 'Latencia de requests IA en milisegundos',
  labelNames: ['model', 'feature', 'status'],
  buckets: [100, 250, 500, 1000, 2500, 5000, 10000]
});

const aiTokens = new Counter({
  name: 'ai_tokens_total',
  help: 'Total de tokens consumidos',
  labelNames: ['model', 'type', 'feature']  // type: input/output
});

const aiCost = new Counter({
  name: 'ai_cost_usd',
  help: 'Coste estimado en USD',
  labelNames: ['model', 'feature']
});

async function instrumentedAICall(params: AICallParams) {
  const startTime = Date.now();

  try {
    const result = await makeAICall(params);

    const latency = Date.now() - startTime;
    aiLatency.observe({
      model: params.model,
      feature: params.feature,
      status: 'success'
    }, latency);

    aiTokens.inc({
      model: params.model,
      type: 'input',
      feature: params.feature
    }, result.usage.inputTokens);

    aiTokens.inc({
      model: params.model,
      type: 'output',
      feature: params.feature
    }, result.usage.outputTokens);

    const cost = calculateCost(params.model, result.usage);
    aiCost.inc({
      model: params.model,
      feature: params.feature
    }, cost);

    return result;
  } catch (error) {
    aiLatency.observe({
      model: params.model,
      feature: params.feature,
      status: 'error'
    }, Date.now() - startTime);

    throw error;
  }
}

Seguimiento de costes: La metrica que capta la atencion de los ejecutivos

Seamos honestos - los costes suelen ser lo que trae las conversaciones de observabilidad a la mesa. Asi es como los trackeas correctamente:

const MODEL_PRICING = {
  'gpt-4-turbo': { input: 0.01, output: 0.03 },      // por 1K tokens
  'gpt-4o': { input: 0.005, output: 0.015 },
  'gpt-4o-mini': { input: 0.00015, output: 0.0006 },
  'claude-3-opus': { input: 0.015, output: 0.075 },
  'claude-3-sonnet': { input: 0.003, output: 0.015 },
  'claude-3-haiku': { input: 0.00025, output: 0.00125 }
};

function calculateCost(model: string, usage: TokenUsage): number {
  const pricing = MODEL_PRICING[model];
  if (!pricing) return 0;

  return (usage.inputTokens / 1000 * pricing.input) +
         (usage.outputTokens / 1000 * pricing.output);
}

// Agregar costes por feature, equipo, cliente
interface CostAllocation {
  feature: string;
  team: string;
  customerId?: string;
  dailyCost: number;
  monthlyProjection: number;
}

Construye dashboards que muestren:

• Gasto diario/semanal/mensual por modelo
• Coste por feature o caso de uso
• Coste por cliente (para B2B)
• Gasto mensual proyectado basado en la trayectoria actual
• Deteccion de anomalias para picos de coste repentinos

Trazado: Siguiendo el hilo

Los workflows IA ya no son llamadas unicas. Son cadenas, agentes y procesos multi-paso complejos. El trazado te permite seguir una request a traves de todo el sistema.

Implementando trazado distribuido

import { trace, SpanKind, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('ai-service');

async function tracedAgentExecution(task: string, context: RequestContext) {
  return tracer.startActiveSpan('agent.execute', async (span) => {
    span.setAttributes({
      'ai.task': task,
      'ai.session_id': context.sessionId,
      'ai.user_id': context.userId
    });

    try {
      // Paso 1: Planificacion
      const plan = await tracer.startActiveSpan('agent.plan', async (planSpan) => {
        const result = await planTask(task);
        planSpan.setAttributes({
          'ai.model': 'gpt-4-turbo',
          'ai.tokens.input': result.usage.input,
          'ai.tokens.output': result.usage.output,
          'ai.plan.steps': result.steps.length
        });
        return result;
      });

      // Paso 2: Ejecutar cada paso
      for (const step of plan.steps) {
        await tracer.startActiveSpan(`agent.step.${step.type}`, async (stepSpan) => {
          stepSpan.setAttributes({
            'ai.step.type': step.type,
            'ai.step.tool': step.tool
          });

          if (step.type === 'llm_call') {
            await tracedLLMCall(step.params, stepSpan);
          } else if (step.type === 'tool_call') {
            await tracedToolCall(step.tool, step.params, stepSpan);
          }
        });
      }

      span.setStatus({ code: SpanStatusCode.OK });
    } catch (error) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: error.message
      });
      span.recordException(error);
      throw error;
    }
  });
}

Lo que muestran los buenos traces

Un trace IA bien instrumentado revela:

[Ejecucion Agente] 4.2s
├── [Planificacion] 1.1s
│   └── [Llamada LLM: gpt-4] 1.0s - 234 tokens entrada, 156 tokens salida
├── [Paso 1: RAG Retrieval] 0.3s
│   ├── [Generacion Embedding] 0.1s
│   └── [Busqueda Vectorial] 0.2s - 5 documentos recuperados
├── [Paso 2: Sintesis LLM] 2.1s
│   └── [Llamada LLM: gpt-4] 2.0s - 1,456 tokens entrada, 523 tokens salida
└── [Paso 3: Formateo Respuesta] 0.7s
    └── [Llamada LLM: gpt-4o-mini] 0.6s - 678 tokens entrada, 234 tokens salida

Ahora cuando alguien reporta una respuesta lenta, puedes ver exactamente donde fue el tiempo.

Debugging de prompts: La parte dificil

Aqui es donde la observabilidad IA diverge mas del monitoreo tradicional. Como debuggeas algo que funciona diferente cada vez?

Versionado de prompts

Trata los prompts como codigo. Versionalos:

interface PromptVersion {
  id: string;
  name: string;
  version: string;
  template: string;
  variables: string[];
  model: string;
  temperature: number;
  createdAt: Date;
  createdBy: string;
  parentVersion?: string;
}

const promptRegistry = {
  'customer-support-v2.3': {
    id: 'cs-001',
    name: 'Agente Soporte Cliente',
    version: '2.3',
    template: `Eres un agente de soporte al cliente util para {{company_name}}.

Tu rol es asistir a los clientes con sus consultas sobre {{product_area}}.

Directrices:
- Siempre verifica la identidad del cliente antes de discutir detalles de cuenta
- Nunca prometas reembolsos sin verificar la politica
- Escala a un agente humano si el cliente expresa frustracion

Consulta del cliente: {{query}}
Contexto: {{context}}`,
    variables: ['company_name', 'product_area', 'query', 'context'],
    model: 'gpt-4-turbo',
    temperature: 0.3
  }
};

A/B Testing de prompts

No puedes mejorar lo que no mides. Ejecuta experimentos en variaciones de prompts:

interface PromptExperiment {
  id: string;
  name: string;
  variants: {
    id: string;
    promptVersion: string;
    trafficPercentage: number;
  }[];
  metrics: string[];  // Que medir
  startDate: Date;
  endDate?: Date;
}

function selectPromptVariant(experimentId: string, userId: string): string {
  const experiment = getExperiment(experimentId);

  // Asignacion deterministica basada en ID de usuario
  const hash = hashString(userId + experimentId);
  const bucket = hash % 100;

  let cumulative = 0;
  for (const variant of experiment.variants) {
    cumulative += variant.trafficPercentage;
    if (bucket < cumulative) {
      return variant.promptVersion;
    }
  }

  return experiment.variants[0].promptVersion;
}

Debuggeando respuestas fallidas

Cuando una respuesta IA sale mal, necesitas responder:

1. Cual fue el input? - Prompt completo incluyendo mensaje de sistema, contexto e input de usuario
2. Que contexto se recupero? - Para sistemas RAG, que documentos influenciaron la respuesta
3. Cual fue el razonamiento del modelo? - Si usas chain-of-thought, que pasos siguio
4. Como afectaron los parametros al output? - Temperature, top_p, frequency penalty
5. Fue puntual o un patron? - Buscar inputs similares que produjeron fallos similares

Construye una interfaz de debugging que te permita:

-- Encontrar fallos similares
SELECT
  request_id,
  prompt_hash,
  response_content,
  error_type,
  timestamp
FROM ai_logs
WHERE
  feature = 'customer-support'
  AND (
    response_content LIKE '%competencia%'    -- Menciono competidores
    OR quality_score < 0.5                    -- Score de calidad bajo
    OR user_feedback = 'negative'             -- Usuario reporto
  )
  AND timestamp > NOW() - INTERVAL '7 days'
ORDER BY timestamp DESC
LIMIT 100;

Monitoreo de calidad: Es la IA realmente buena?

Esta es la parte mas dificil de la observabilidad IA. Las metricas tecnicas pueden estar verdes mientras la IA produce basura.

Controles de calidad automatizados

interface QualityCheck {
  name: string;
  check: (response: AIResponse, context: RequestContext) => QualityResult;
}

const qualityChecks: QualityCheck[] = [
  {
    name: 'response_length',
    check: (response) => ({
      pass: response.content.length > 50 && response.content.length < 5000,
      score: normalizeLength(response.content.length),
      reason: 'Longitud de respuesta dentro del rango aceptable'
    })
  },
  {
    name: 'no_hallucinated_urls',
    check: (response) => {
      const urls = extractUrls(response.content);
      const validUrls = urls.filter(url => isKnownValidUrl(url));
      return {
        pass: urls.length === validUrls.length,
        score: urls.length === 0 ? 1 : validUrls.length / urls.length,
        reason: `${urls.length - validUrls.length} URLs potencialmente alucinadas`
      };
    }
  },
  {
    name: 'factual_grounding',
    check: (response, context) => {
      // Verificar si las afirmaciones clave estan soportadas por el contexto recuperado
      const claims = extractClaims(response.content);
      const groundedClaims = claims.filter(claim =>
        isClaimSupportedByContext(claim, context.retrievedDocuments)
      );
      return {
        pass: groundedClaims.length / claims.length > 0.8,
        score: groundedClaims.length / claims.length,
        reason: `${groundedClaims.length}/${claims.length} afirmaciones ancladas en contexto`
      };
    }
  },
  {
    name: 'safety_check',
    check: (response) => {
      const safetyResult = runSafetyClassifier(response.content);
      return {
        pass: safetyResult.safe,
        score: safetyResult.confidence,
        reason: safetyResult.category || 'Respuesta paso el control de seguridad'
      };
    }
  }
];

async function evaluateResponse(
  response: AIResponse,
  context: RequestContext
): Promise<QualityReport> {
  const results = await Promise.all(
    qualityChecks.map(check => ({
      check: check.name,
      ...check.check(response, context)
    }))
  );

  return {
    overallScore: average(results.map(r => r.score)),
    allPassed: results.every(r => r.pass),
    details: results
  };
}

Evaluacion humana en el bucle

Los controles automatizados capturan problemas obvios. Para problemas de calidad sutiles, necesitas revision humana:

interface HumanEvaluationQueue {
  // Muestrear un porcentaje de respuestas para revision humana
  sampleRate: number;

  // Siempre revisar ciertos tipos
  alwaysReviewWhen: {
    lowConfidence: boolean;           // Incertidumbre del modelo
    userFeedbackNegative: boolean;
    automatedChecksFailed: boolean;
    highValueCustomer: boolean;
  };

  // Criterios de evaluacion para reviewers
  criteria: {
    accuracy: 'La respuesta contenia informacion correcta?';
    relevance: 'La respuesta abordo la consulta del usuario?';
    completeness: 'La respuesta fue suficientemente completa?';
    tone: 'El tono fue apropiado para el contexto?';
    safety: 'Hubo elementos preocupantes?';
  };
}

Alertas: Saber cuando las cosas van mal

Umbrales de alerta para sistemas IA

Implementando alertas inteligentes

interface AIAlert {
  name: string;
  condition: (metrics: AIMetrics) => boolean;
  severity: 'info' | 'warning' | 'critical';
  cooldown: number;  // Minutos antes de re-alertar
  notification: {
    slack?: string;
    pagerduty?: string;
    email?: string[];
  };
}

const alerts: AIAlert[] = [
  {
    name: 'high_latency',
    condition: (m) => m.latencyP95 > 10000,
    severity: 'warning',
    cooldown: 30,
    notification: { slack: '#ai-alerts' }
  },
  {
    name: 'quality_degradation',
    condition: (m) => m.qualityScore < 0.7 && m.previousQualityScore > 0.85,
    severity: 'critical',
    cooldown: 60,
    notification: {
      slack: '#ai-alerts',
      pagerduty: 'ai-oncall'
    }
  },
  {
    name: 'cost_anomaly',
    condition: (m) => m.hourlyCost > m.expectedHourlyCost * 3,
    severity: 'warning',
    cooldown: 60,
    notification: {
      slack: '#ai-alerts',
      email: ['ai-team@company.com']
    }
  }
];

Construyendo tu stack de observabilidad

Arquitectura recomendada

┌─────────────────────────────────────────────────────────────────┐
│                        Aplicacion IA                             │
├─────────────────────────────────────────────────────────────────┤
│                     Capa de Instrumentacion                      │
│  (OpenTelemetry SDK, Metricas Custom, Logging Estructurado)     │
└─────────────────────────────┬───────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐   ┌─────────────────┐   ┌───────────────┐
│    Traces     │   │    Metricas     │   │     Logs      │
│   (Jaeger/    │   │  (Prometheus/   │   │ (Elasticsearch│
│    Tempo)     │   │   Datadog)      │   │   /Loki)      │
└───────┬───────┘   └────────┬────────┘   └───────┬───────┘
        │                    │                    │
        └────────────────────┼────────────────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │   Dashboards    │
                    │    (Grafana)    │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │    Alerting     │
                    │  (PagerDuty/    │
                    │   Slack/OpsGenie│
                    └─────────────────┘

Herramientas que recomendamos

Ejemplo del mundo real: Setup completo de observabilidad

Asi es como instrumentamos una feature IA en produccion de principio a fin:

import { trace, metrics, context } from '@opentelemetry/api';
import { logger } from './logging';
import { qualityChecker } from './quality';
import { costTracker } from './costs';

class ObservableAIService {
  private tracer = trace.getTracer('ai-service');
  private meter = metrics.getMeter('ai-service');

  private latencyHistogram = this.meter.createHistogram('ai.latency');
  private tokenCounter = this.meter.createCounter('ai.tokens');
  private costCounter = this.meter.createCounter('ai.cost');
  private qualityGauge = this.meter.createObservableGauge('ai.quality');

  async complete(request: AIRequest): Promise<AIResponse> {
    const span = this.tracer.startSpan('ai.complete');
    const startTime = Date.now();

    const requestId = generateRequestId();
    span.setAttribute('request_id', requestId);
    span.setAttribute('model', request.model);
    span.setAttribute('feature', request.feature);

    try {
      // Loggear la request
      logger.info('ai.request.start', {
        requestId,
        model: request.model,
        feature: request.feature,
        promptHash: hashPrompt(request.prompt),
        inputTokenEstimate: estimateTokens(request.prompt)
      });

      // Hacer la llamada IA
      const response = await this.makeAICall(request);

      const latency = Date.now() - startTime;
      const cost = costTracker.calculate(request.model, response.usage);

      // Registrar metricas
      this.latencyHistogram.record(latency, {
        model: request.model,
        feature: request.feature,
        status: 'success'
      });

      this.tokenCounter.add(response.usage.inputTokens, {
        model: request.model,
        type: 'input'
      });

      this.tokenCounter.add(response.usage.outputTokens, {
        model: request.model,
        type: 'output'
      });

      this.costCounter.add(cost, {
        model: request.model,
        feature: request.feature
      });

      // Ejecutar controles de calidad
      const quality = await qualityChecker.evaluate(response, request);

      // Loggear la respuesta
      logger.info('ai.request.complete', {
        requestId,
        latencyMs: latency,
        inputTokens: response.usage.inputTokens,
        outputTokens: response.usage.outputTokens,
        costUsd: cost,
        qualityScore: quality.overallScore,
        qualityPassed: quality.allPassed
      });

      // Almacenar para debugging (con retencion apropiada)
      await this.storeForDebugging(requestId, request, response, quality);

      span.setStatus({ code: SpanStatusCode.OK });
      return response;

    } catch (error) {
      const latency = Date.now() - startTime;

      this.latencyHistogram.record(latency, {
        model: request.model,
        feature: request.feature,
        status: 'error'
      });

      logger.error('ai.request.error', {
        requestId,
        error: error.message,
        errorType: error.constructor.name,
        latencyMs: latency
      });

      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
      span.recordException(error);

      throw error;
    } finally {
      span.end();
    }
  }
}

Empezando: Tu primera semana

Dia 1-2: Logging basico

• Anadir logging estructurado a todas las llamadas IA
• Incluir: modelo, latencia, contadores de tokens, nombre de feature
• Almacenar logs en algun lugar consultable

Dia 3-4: Metricas core

• Configurar contadores de tokens y costes
• Crear histogramas de latencia por modelo y feature
• Construir tu primer dashboard

Dia 5: Alerting

• Alertar en picos de tasa de error
• Alertar en anomalias de coste
• Alertar en degradacion de latencia

Semana 2: Calidad y Tracing

• Implementar controles de calidad basicos
• Anadir tracing distribuido para workflows IA multi-paso
• Empezar a recolectar feedback de usuarios

Conclusion

La observabilidad IA ya no es opcional. A medida que los sistemas IA manejan workflows mas criticos, necesitas saber no solo si estan funcionando, sino si estan trabajando correctamente.

La buena noticia: la mayoria de lo que necesitas puede construirse sobre infraestructura de observabilidad existente. OpenTelemetry, Prometheus, logging estructurado - estas herramientas funcionan para IA tambien. La diferencia esta en saber que medir y como interpretarlo.

Empieza simple. Loggea todo. Trackea costes. Anade controles de calidad. Construye desde ahi.

El mejor momento para anadir observabilidad fue antes del lanzamiento. El segundo mejor momento es ahora.

Hemos ayudado a equipos a pasar de "no tenemos idea de que esta haciendo nuestra IA" a "detectamos ese problema en 3 minutos" en cuestion de semanas. La inversion se paga sola la primera vez que debuggeas un problema de produccion en minutos en lugar de horas.

Si estas construyendo sistemas IA y quieres hablar sobre estrategias de observabilidad, contactanos. Hemos visto muchos modos de fallo y estamos encantados de compartir lo que hemos aprendido.