Volver

📋 Guía de Logs - NorthTec AI

Sistema de logging estructurado para Cloud Run

📊 Google Cloud Console (Logs Explorer)

Queries de Ejemplo

CHAT Buscar todos los requests de chat
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.cat="CHAT"
IDENTITY Buscar validaciones de identidad fallidas
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.evt=~"identity.validate.*fail"
RAG Buscar queries RAG por namespace
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.cat="RAG"
jsonPayload.namespace="CLIENT_NAMESPACE"
🔍 Buscar por conversación específica
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.conversationId="conv_xxxxxxxxxxxxx"
👤 Buscar por cliente específico
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.clientId="CLIENT_ID"
ERRORES Buscar solo errores
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
severity>=ERROR
🔢 Buscar por cédula específica
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.idNumber="113030227"

💻 Comandos gcloud CLI

💡 Tip: Estos comandos funcionan en la terminal. Asegurate de tener gcloud instalado y configurado.
CHAT Ver requests de chat
# Todos los requests de chat
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "chat.request"

# Ver qué persona/role se usa
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "chat.request" | grep -o '"role":"[^"]*"'
IDENTITY Ver validaciones de identidad
# Todas las validaciones
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "identity.validate"

# Solo las fallidas
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "identity.validate.*fail"

# Solo las exitosas
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "identity.validate.*_ok"
RAG Ver queries RAG
# Queries exitosos
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "rag.query.success"

# Queries fallidos
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "rag.query.error"

# Ver chunks encontrados
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "rag.query" | grep -o '"chunksCount":[0-9]*'
TOOLS Ver ejecución de tools
# Todos los tools ejecutados
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "tool.invoke"

# Solo errores de tools
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "tool.invoke.error"
🔍 Búsquedas por filtro
# Por categoría
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep '"cat":"IDENTITY"'

# Por evento específico
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep '"evt":"chat.request"'

# Por conversationId
gcloud run logs read northtec-ia --region us-central1 --limit 100 | grep "conv_xxxxx"

# Por clientId
gcloud run logs read northtec-ia --region us-central1 --limit 100 | grep '"clientId":"CLIENT_ID"'
Filtrar por tiempo
# Últimos 30 minutos
gcloud run logs read northtec-ia --region us-central1 --limit 200 --freshness=30m

# Última hora
gcloud run logs read northtec-ia --region us-central1 --limit 500 --freshness=1h

# Últimas 24 horas
gcloud run logs read northtec-ia --region us-central1 --limit 1000 --freshness=1d

📁 Categorías de Logs

CHAT

Requests y responses del chat, configuración de persona, modo manual.

IDENTITY

Validación de cédulas, llamadas a endpoints primary/failover.

RAG

Queries de contexto, embeddings, búsqueda en Pinecone.

TOOL

Ejecución de herramientas MCP (validate_identity, emit_policy, etc).

AUTH

Validación de tokens, API keys, permisos.

WIDGET

Inicialización de widget, mensajes polling, rate limiting.

WHATSAPP

Webhooks, mensajes entrantes/salientes, rate limiting, conversaciones.


📋 Eventos Disponibles

Categoría Evento Descripción
CHAT chat.request Nuevo request de chat recibido
CHAT chat.response Response enviado al cliente
CHAT chat.error Error en el procesamiento del chat
CHAT chat.manual_mode Conversación en modo manual
IDENTITY identity.validate.primary_ok Validación exitosa en endpoint primario
IDENTITY identity.validate.primary_fail Fallo en endpoint primario
IDENTITY identity.validate.failover_ok Validación exitosa en endpoint de respaldo
IDENTITY identity.validate.failover_fail Fallo en endpoint de respaldo
IDENTITY identity.validate.error Ambos endpoints fallaron
RAG rag.query.start Inicio de query RAG
RAG rag.query.success Query RAG exitoso
RAG rag.query.error Error en query RAG
TOOL tool.invoke.start Inicio de ejecución de tool
TOOL tool.invoke.success Tool ejecutado exitosamente
TOOL tool.invoke.error Error en ejecución de tool

📱 Eventos WhatsApp

WHATSAPP Buscar eventos de WhatsApp
# Todos los eventos WhatsApp
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "whatsapp."

# Solo mensajes entrantes
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "whatsapp.message.received"

# Solo rate limiting
gcloud run logs read northtec-ia --region us-central1 --limit 50 | grep "whatsapp.rate_limit"
Evento Descripción Campos Útiles
whatsapp.webhook.verified Webhook verificado exitosamente keyId
whatsapp.webhook.verification_failed Fallo en verificación de webhook hasToken
whatsapp.webhook.authenticated Firma de Meta validada keyId, phoneNumberId
whatsapp.webhook.invalid_signature Firma de Meta inválida phoneNumberId
whatsapp.webhook.key_paused Key está pausada keyId
whatsapp.message.received Mensaje recibido de usuario keyId, from (últimos 4 dígitos), type
whatsapp.message.sent Mensaje enviado al usuario conversationId, success, messageId
whatsapp.message.rate_limited Mensaje rechazado por rate limit keyId, from, reason
whatsapp.conversation.found Conversación encontrada/creada conversationId, isNew, from
whatsapp.status_update Actualización de estado de mensaje status, messageId
whatsapp.rate_limit.blocked Request bloqueado por rate limit keyId, reason
whatsapp.rate_limit.exceeded Límite global excedido keyId, currentCount, limit
whatsapp.rate_limit.user_exceeded Límite por usuario excedido keyId, phoneNumber, reason

Queries Cloud Console - WhatsApp

📱 Buscar mensajes de un número específico
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.cat="WHATSAPP"
jsonPayload.from=~"5678"  // Últimos 4 dígitos
⚠️ Buscar problemas de rate limiting WhatsApp
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.evt=~"whatsapp.rate_limit.*"
🔐 Buscar problemas de autenticación WhatsApp
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.evt=~"whatsapp.webhook.invalid.*|whatsapp.webhook.key_paused"

🔍 Campos Disponibles para Filtrar

Campo Tipo Descripción Ejemplo
cat string Categoría del log CHAT, IDENTITY, RAG, TOOL
evt string Evento específico chat.request, identity.validate.primary_ok
conversationId string ID de la conversación conv_abc123xyz
clientId string ID del cliente client_xyz789
role string Rol del asistente assistant, advisor, support, sales
tone string Tono de comunicación professional, friendly, casual
assistantName string Nombre del asistente Sofia, Asistente LAFISE
toolName string Nombre del tool ejecutado validate_identity, emit_policy
idType string Tipo de identificación cedula, passport
idNumber string Número de identificación 113030227
endpoint string Endpoint usado primary, failover
httpStatus number Código HTTP de respuesta 200, 404, 500
hasClient boolean Si se encontró el cliente true, false
namespace string Namespace de Pinecone client_namespace
chunksCount number Cantidad de chunks encontrados 5
contextLength number Longitud del contexto 2500
durationMs number Duración en milisegundos 1234
error string Mensaje de error both_endpoints_failed
source string Origen del request api, widget, whatsapp
platform string Plataforma del cliente ios, android, web
ragEnabled boolean Si RAG está habilitado true, false
keyId string ID de la WhatsApp key wa_abc123
phoneNumberId string Phone Number ID de Meta 123456789012345
from string Últimos 4 dígitos del número 5678
fromName string Nombre del perfil WhatsApp Juan Pérez
type string Tipo de mensaje WhatsApp text, image, audio, document

📝 Ejemplos de Uso Común

🔍 Investigar por qué falló una validación de cédula
# 1. Buscar todas las validaciones de esa cédula
gcloud run logs read northtec-ia --region us-central1 --limit 100 | grep "113030227"

# 2. En Cloud Console, query más específico
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.idNumber="113030227"
jsonPayload.cat="IDENTITY"
🔍 Ver todas las conversaciones de un cliente
# En Cloud Console
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.clientId="CLIENT_ID"
jsonPayload.evt="chat.request"
🔍 Ver qué rol/persona se usa más
# Extraer roles de los últimos 200 requests
gcloud run logs read northtec-ia --region us-central1 --limit 200 | \
  grep "chat.request" | \
  grep -o '"role":"[^"]*"' | \
  sort | uniq -c | sort -rn
🔍 Ver rendimiento de RAG (chunks y duración)
# En Cloud Console
resource.type="cloud_run_revision"
resource.labels.service_name="northtec-ia"
jsonPayload.evt="rag.query.success"

# Ver estadísticas
gcloud run logs read northtec-ia --region us-central1 --limit 100 | \
  grep "rag.query.success" | \
  grep -o '"chunksCount":[0-9]*' | \
  cut -d: -f2 | \
  awk '{sum+=$1; count++} END {print "Average chunks:", sum/count}'
🔍 Monitorear errores en tiempo real
# Stream de errores en vivo (requiere gcloud beta)
gcloud beta run logs tail northtec-ia --region us-central1 2>&1 | grep -i "error\|fail"