event_log (logging estructurado)

Toda la observabilidad se apoya en una única tabla append-only, event_log (src/event-log/). Es a la vez herramienta de debugging y combustible del flywheel.

La tabla

Columna	Notas
id	UUID
event_date	timestamptz (default now), indexado
event	enum event_type
call_id / agent_id	referencias de la llamada / agente
user_id / user_email	identidad del usuario autenticado (solo en acciones de usuario)
entity_id / entity_type	referencia genérica
payload	jsonb flexible por tipo de evento

EventLogService.log(event, context) es fire-and-forget (void ...): si falla, loguea el error pero nunca rompe el flujo de la llamada.

Tipos de evento

Evento	Cuándo	Payload destacado
call_started / call_ended	inicio/fin de llamada	source, callerNumber
knowledge_queried	cada recuperación RAG (hit y miss)	query, hit, scores, embedMs, queryMs, reason
suggestion_generated	se generó una sugerencia	chars, llmMs, ragHit, ragScore, tokens
feedback_given	el operario marcó una sugerencia	action, suggestionId
claim_initiated	un agente tomó una llamada	source
call_released	un agente liberó una llamada	source
transfer_initiated	derivación a humano (Retell)	patient, summaryChars
memory_created	se guardó una lección (flywheel)	category

Identidad del usuario

user_id / user_email solo se pueblan en acciones que entran por HTTP autenticado (feedback, claim, release), tomadas de @CurrentUser() en el controller.

agent_id NO es la identidad del usuario

agent_id es el último segmento de la URL del WebSocket del copiloto (VITE_COPILOT_WS_URL), frecuentemente 'unknown'. Para auditoría (quién hizo qué) usar user_id / user_email. Los eventos del bot (RAG, sugerencias, inicio/fin) no tienen usuario.

Qué alimenta

• Métricas operativas (cobertura, se calló/derivó, latencia) → panel /operations.
• Auditoría de acciones de usuario → panel /logs.

Ver Métricas y paneles.