Biblioteca de Métricas

Si conocés los Widgets de Uso del cliente (Configuración → Widgets de Uso), las Métricas son su evolución natural. Un widget responde una pregunta acotada — "¿cuántos eventos X hubo en los últimos Y días?". Una métrica responde cualquier pregunta sobre los eventos del producto, con filtros, ventanas calendario y grano per-cliente o de portafolio. Y, lo más importante, una métrica se conecta con objetivos del cliente, drivers de salud y triggers de playbooks — no es solo un número en un dashboard.

La Biblioteca de Métricas es donde el admin del workspace define una vez, para que el resto del producto consuma. Esto evita que cada CSM invente su propia versión de "usuarios activos" o "tickets críticos".

Qué es una métrica

Una métrica es una definición declarativa que describe cómo calcular un número a partir de los eventos que LealUp ya está ingiriendo. Cada métrica tiene:

• Nombre y slug — etiqueta humana + identificador único en tu LealUp.
• Evento fuente — el evento del producto que se va a contar / sumar / promediar.
• Tipo de cálculo — qué operación aplicar.
• Filtro — condiciones opcionales sobre las propiedades del evento.
• Ventana — en qué período de tiempo mirar.
• Grano — si se calcula por cliente o para todo el portafolio.
• Unidad — opcional, para mostrar bonito en la UI (usuarios, USD, tickets).

Una vez definida, LealUp la calcula automáticamente y la deja disponible para que cualquier objetivo, driver de salud o trigger de playbook la use.

Métricas vs. Widgets de Uso

Los Widgets de Uso siguen funcionando — no se van a ningún lado. La Biblioteca de Métricas es el siguiente paso para casos que el formato widget no cubre.

Resumen: si solo querés un panel con cuántas veces ocurrió algo, el Widget de Uso te alcanza. Si necesitás conectar ese número a la salud, a un objetivo del cliente o a un playbook, usá una métrica.

Antes de crear métricas: ¿qué eventos necesito enviar?

Una métrica solo puede calcular sobre eventos que tu producto ya está mandando a LealUp. Si tu equipo todavía no instrumentó eventos, las métricas no van a tener nada que medir. Esta sección resume qué hacer del lado de tu producto antes de empezar a definir métricas.

Qué es un evento, en concreto

Un evento es un hecho ocurrido en tu producto, asociado a un cliente del workspace. La forma mínima usa tu propio ID del cliente — LealUp lo resuelve internamente:

{
  "external_customer_id": "acme_42",   // tu ID del cliente (CRM, base de datos, etc.)
  "external_source": "internal",        // opcional, default "internal"
  "event_name": "report_exported",      // snake_case, estable en el tiempo
  "user_id": "u_12345",                 // quién lo disparó (opcional pero recomendado)
  "timestamp": "2026-04-15T14:25:00Z",  // cuándo ocurrió, ISO 8601 con TZ
  "properties": {                       // payload arbitrario; usá keys snake_case
    "report_type": "quarterly",
    "format": "pdf",
    "amount_usd": 99
  }
}

Alternativa: si ya tenés guardado el UUID interno de LealUp, podés enviarlo como customer_id en lugar de external_customer_id. Solo enviá uno de los dos.

Cada campo de properties que envíes es un campo que después vas a poder usar como propiedad objetivo (sum, max, avg, distinct count) o como filtro en una métrica. Si nunca enviás properties.user_role, ese campo no va a aparecer en el builder de métricas.

Cómo llegan los eventos a LealUp

Tres caminos, no son excluyentes:

1. Endpoint HTTP de LealUp — tu backend o un job programado hace POST /v1/ingest/events con un batch de hasta 100 eventos. Es el camino estándar y el más explícito. Ver Ingesta de eventos para schema completo, batching, idempotencia y rate limits.
2. Conectores nativos — si ya mandás eventos a PostHog, Mixpanel, Amplitude o Segment, no los reingestes. Conectá la fuente desde Configuración → Integraciones y LealUp extrae los eventos relevantes. Ver Otras integraciones.
3. Eventos que LealUp genera por vos — email_sent, email_received, meeting_held, ticket_opened, ticket_closed, task_completed, health_changed aparecen automáticamente desde Gmail, Calendar, Zendesk, Jira y los playbooks. No los dupliques con ingesta manual.

Quién hace cada cosa

Las métricas las define el admin del workspace en LealUp, pero la instrumentación de eventos la hace tu equipo de ingeniería del lado del producto. Una conversación típica antes de pilotar:

• Vos (admin del workspace) definís qué necesitás medir: "queremos un objetivo de adopción que cuente reportes exportados por cliente".
• Tu equipo de producto acuerda el event_name (report_exported), las properties que va a mandar (format, report_type, size_mb) y el momento del flujo en que se dispara el evento.
• Tu equipo de ingeniería instrumenta el evento con el SDK o el endpoint, o conecta una fuente existente.
• Vos verificás en Admin → Datos → Ingesta → Logs que los eventos están llegando.
• Vos definís la métrica en la Biblioteca y la vinculás al objetivo / driver de salud / trigger de playbook.

Sin instrumentación, las métricas se quedan sin datos.

Catálogo de eventos del workspace

LealUp mantiene un catálogo de eventos (configurable en Configuración → Eventos). El catálogo es la fuente de verdad de qué eventos existen en tu workspace y qué significan. Cuando creás una métrica, el buscador del campo Evento fuente lee de este catálogo.

• Los eventos nuevos que llegan via ingesta aparecen en el catálogo automáticamente la primera vez.
• Podés (y deberías) anotar cada evento con un nombre amigable, una categoría de ciclo de vida y un score, para que el resto del producto lo use bien.
• Si necesitás crear una métrica contra un evento que todavía no llegó nunca al sistema, primero hay que mandarlo (al menos una vez) o registrarlo manualmente desde el admin.

Checklist antes de definir tu primera métrica

• Los clientes a los que querés medir están provisionados en el workspace.
• Tu equipo definió el event_name y la lista de properties que va a enviar.
• El evento se está enviando a LealUp (vía API, conector o evento del sistema).
• Aparece en Admin → Datos → Ingesta → Logs (al menos un evento exitoso).
• Aparece en Configuración → Eventos con su nombre amigable.
• Podés ver el evento en la sección Eventos de la ficha de algún cliente.

Cumplido ese checklist, ya podés crear la métrica.

Errores frecuentes

• Referencia al cliente desconocida — si enviás external_customer_id y no resuelve, el evento se rechaza con código unknown_external_customer; lo mismo aplica para customer_id con código unknown_customer. Mirá la respuesta del endpoint o los logs de ingesta. Provisioná el cliente primero.
• Cambio de tipo de una property — si arrancás mandando amount_usd: 99 (entero) y después amount_usd: "99" (string), las métricas sum / avg se rompen sin aviso. Mantené tipos estables.
• Renombrar un evento existente — perdés la historia. Si necesitás cambiarlo, creá uno nuevo (report_exported_v2).
• PII innecesaria en properties — no envíes nombres, emails o direcciones salvo que los necesites en una métrica. Si los necesitás, hablalo con el equipo.
• Eventos ruidosos (button_hovered, scroll) — saturan el storage y no aportan a métricas útiles.

Para todo el detalle del contrato (schema completo, batching, deduplicación con external_id, rate limits, backfill histórico, SDKs y debugging) ver Ingesta de eventos.

Cómo llegar

Configuración → Biblioteca de Métricas

Vas a ver la lista de métricas del workspace con columnas para nombre, evento fuente, tipo de cálculo, grano, última materialización y autor. Las métricas creadas con asistencia de IA llevan el ícono ✨.

Tipos de cálculo

Una métrica puede aplicar uno de estos cálculos sobre los eventos que matchean su filtro y ventana:

Para sum, max, avg y distinct count necesitás indicar qué propiedad del evento se opera (target_property).

Ventana

La ventana define en qué rango de tiempo mirar los eventos:

• Rolling (móvil) — los últimos N días contados desde hoy. Ejemplo: rolling 30 días recalcula cada hora y siempre cubre los últimos 30 días.
• Calendar (calendario) — un período fijo: día actual, semana actual, mes actual, trimestre actual. Útil para reportar contra ciclos del negocio (cierres mensuales, trimestrales).

Rolling 7 días   → eventos entre hoy-7 y hoy
Calendar mes     → eventos del 1ro del mes hasta hoy

Grano

El grano define si la métrica se calcula a nivel cliente o agregada a todo el portafolio:

• Per-cliente — el cálculo se repite para cada cliente del workspace. Cada cliente tiene su propio valor. Es lo que necesitás para usar la métrica en objetivos individuales o en la salud del cliente.
• Portafolio — un único valor agregado para todo el workspace. Útil para dashboards globales y triggers de playbook que evalúan el estado general (ej. "si el ARR total cae 5% lanzá el playbook de save").

La mayoría de las métricas son per-cliente.

Crear una métrica manualmente

1. Configuración → Biblioteca de Métricas → + Nueva métrica.
2. Se abre el Builder Drawer a la derecha. Completá las secciones:

Identidad

• Nombre — etiqueta visible (ej. "Reportes creados por mes").
• Slug — identificador único en el workspace (ej. reports_created_monthly). Se autogenera desde el nombre, podés editarlo.
• Descripción — opcional pero recomendada. Otros admins van a entender qué mide.

Fuente

• Evento fuente — buscador con autocompletado sobre los eventos definidos en tu workspace. Si no aparece el evento que buscás, todavía no llegó al sistema o no está registrado.

Cálculo

• Tipo de cálculo — radio: count / sum / max / avg / distinct count / last value / exists.
• Propiedad objetivo (target_property) — solo aparece para sum, max, avg, distinct count. Es la propiedad numérica del evento que se opera.
• Filtro — opcional. Builder JSON con filas campo / operador / valor. Operadores soportados: eq, neq, gt, gte, lt, lte, contains, in. Ejemplo:

field: properties.user_role
op:    eq
value: "admin"

• Ventana — rolling N días o calendar (día / semana / mes / trimestre).
• Grano — per-cliente o portafolio.
• Unidad — opcional. Cómo se muestra el número.

Acciones

• Probar consulta — antes de guardar, ejecuta la métrica sobre una muestra de clientes y devuelve los valores. Te asegura que la definición está bien antes de que la consuma medio workspace.
• Guardar — la métrica queda activa. El job de materialización la levanta en el siguiente tick (hasta una hora).
• Cancelar — descarta los cambios.

Crear una métrica con IA

Si describís la métrica en lenguaje natural, la IA arma la definición por vos.

1. + Nueva métrica → en el header del drawer click en ✨ Sugerir con IA.
2. Se despliega el panel Sugerencia de IA. Escribí el prompt en lenguaje natural:

"número de reportes creados por mes por usuarios admin"
"tickets críticos abiertos en los últimos 14 días"
"última fecha en que el cliente facturó"

3. Click en ✨ Generar. La IA devuelve una propuesta de definición con:
   • Evento fuente sugerido.
   • Tipo de cálculo y propiedad objetivo.
   • Filtros propuestos.
   • Ventana y grano.
   • Justificación y nivel de confianza.
4. Tenés tres acciones:
   • Aceptar — el formulario se pre-llena con la propuesta. Podés guardar directo o ajustar antes.
   • Editar — el formulario se pre-llena pero quedás en modo edición para ajustar campos.
   • Rechazar — descarta la propuesta y volvés al builder vacío.
5. Antes de guardar, siempre ejecutá Probar consulta para verificar que el resultado tiene sentido.

La IA valida la propuesta contra el catálogo de eventos del workspace, así que no va a inventar nombres de eventos o propiedades inexistentes. Aún así, la sugerencia es un punto de partida — la decisión final es tuya.

Probar la consulta antes de guardar

El botón Probar consulta ejecuta la métrica contra una muestra de clientes (típicamente 5-10) y devuelve los valores en una tabla:

Cliente              Valor    Período
Acme Corp            142      2026-04-04 → 2026-05-03
Contoso              87       2026-04-04 → 2026-05-03
Fabrikam             0        2026-04-04 → 2026-05-03

Si ves valores raros (todo 0, valores fuera de rango, error), revisá el filtro y el evento fuente antes de guardar. Una métrica mal definida que llega a producción puede romper objetivos y disparar playbooks por error.

Migrar un Widget de Uso a una métrica

Los Widgets de Uso existentes siguen funcionando, pero si querés conectar uno a un objetivo, a la salud o a un playbook, lo tenés que recrear como métrica. La migración es manual en esta versión:

1. Anotá la configuración del widget actual desde Configuración → Widgets de Uso: evento fuente, agregación, período, etiqueta.
2. Configuración → Biblioteca de Métricas → + Nueva métrica.
3. Mapeá los campos del widget al builder de métrica:

4. Grano: per-cliente (los widgets son siempre por cliente).
5. Probar consulta y Guardar.
6. Ahora podés vincular un objetivo, driver de salud o trigger de playbook a esa métrica.

No hace falta eliminar el widget original — pueden coexistir. Si querés, dejá el widget para visualización rápida en la ficha del cliente y usá la métrica para los objetivos / salud / playbooks.

Cómo se usa una métrica

Una vez guardada, una métrica está disponible en cuatro lugares:

En objetivos

Los CSMs pueden vincular un objetivo del cliente a una métrica. El valor actual del objetivo se actualiza automáticamente desde la métrica y aparece marcado como "Calculado automáticamente desde la métrica".

Ver Vincular un objetivo a una métrica.

En drivers de salud

Podés definir un driver del modelo de salud usando una métrica de la biblioteca, en vez de los drivers hard-coded. Esto te deja modelar dimensiones específicas de tu producto sin tocar código.

Ver Drivers desde métricas.

En triggers de playbooks

Los playbooks soportan un nuevo tipo de trigger: metric_threshold. Cuando la métrica cruza un umbral, el playbook se dispara para ese cliente.

si métrica "Logins en últimos 7 días" < 5 → lanzá playbook "Reactivación"

En la ficha del cliente

Las métricas per-cliente se muestran en la sección Métricas calculadas de la ficha 360, con el último valor y la marca de tiempo.

Cuándo se actualiza

• Las métricas se materializan cada hora mediante un job en background.
• Solo se calculan para los clientes que tienen un consumidor activo de la métrica (un objetivo vinculado, un driver de salud o un trigger de playbook). Esto evita gastar cómputo en métricas definidas pero no usadas.
• La primera materialización después de crear la métrica puede tardar hasta una hora — es esperable.
• Si necesitás un cálculo inmediato (ej. probaste y querés validar en producción), pedí al equipo de soporte un forzar materialización o usá la opción de admin.

Editar una métrica

Para preservar la integridad de los datos históricos, las métricas tienen edición limitada:

• Editable: nombre, descripción, unidad.
• No editable una vez creada: evento fuente, tipo de cálculo, propiedad objetivo, filtro, ventana, grano.

Si necesitás cambiar uno de los campos no editables, creá una métrica nueva con la definición correcta y migrá los consumidores (objetivos, drivers, triggers) a la nueva métrica. La vieja queda disponible mientras tenga consumidores, y la podés borrar cuando ya no la use nadie.

Esta restricción evita que un cambio sutil en el filtro rompa silenciosamente objetivos y dispare playbooks por error.

Eliminar una métrica

Click en ••• sobre una métrica → Eliminar.

LealUp bloquea la eliminación si la métrica todavía está en uso por al menos un objetivo, driver de salud o trigger de playbook. La UI te dice exactamente quiénes la usan para que puedas migrarlos primero.

Cuando se elimina, la métrica se marca como soft-deleted; sus valores históricos quedan disponibles para auditoría pero ya no se materializan más.

Buenas prácticas

• Nombres descriptivos — "Reportes creados último mes (admin)" es mejor que "Reportes admin". Otros admins van a leer estos nombres en pickers de objetivos sin contexto.
• Una métrica = una pregunta — si necesitás distintos filtros, creá métricas separadas. No reutilices una métrica para dos casos parecidos.
• Probá siempre antes de guardar — la mitad de los problemas de salud o playbooks vienen de métricas mal definidas.
• Documentá el porqué — usá el campo descripción para explicar qué decisión de negocio respalda la métrica. En 6 meses tu yo del futuro te lo va a agradecer.
• Empezá con count y sum — son los cálculos más fáciles de razonar y los que cubren el 80% de los casos.

Permisos

• Admin — crear, editar y eliminar métricas. Acceso completo a la biblioteca.
• CSM / Viewer — ver el catálogo (para entender qué métricas existen) y consumirlas en objetivos. No pueden crear ni editar.

Si sos CSM y necesitás una métrica nueva, pedísela al admin del workspace o usá Alfred para sugerirla.