Saltar al contenido
Telemetry
Explorar documentación
GuíasActualizado el 27 de julio de 2026Revisado por los equipos editorial y de producto de Telemetry4 min de lectura

Usa esta documentación con tu agente de programación

Abra un paquete de mensajes enfocados para Claude Code, Codex, Cursor u otro agente de codificación, luego adáptelo al flujo de trabajo que se describe aquí.

En esta página
  1. 1. Defina el embudo antes de agregar eventos.
  2. 2. Registre una forma de evento consistente
  3. 3. Calcule el embudo en una consulta.
  4. 4. Segmentar sin cambiar la definición
  5. 5. Visualiza y valida el resultado.
  6. Próximos pasos

Medición de tasas de conversión con SQL

Una tasa de conversión general le indica el resultado. Los eventos de hitos lo explican mostrando dónde abandonan los usuarios el embudo y qué segmento cambió.

Embudo de conversión de cuatro pasos desde la vista de la página de destino hasta el registro, el pago y la conversión paga

Las tasas de conversión de pasos adyacentes hacen que la caída más grande sea inmediatamente visible.

Esta guía crea un embudo de registro a nivel de usuario en una tabla de eventos y una consulta SQL. Contar distintos usuarios en cada etapa evita inflar la conversión cuando una persona repite una acción.

1. Defina el embudo antes de agregar eventos.

Utilice hitos que representen resultados completados, no clics en botones que puedan fallar:

  1. signup_completed
  2. workspace_created
  3. first_event_received
  4. dashboard_created

Elija un identificador de sujeto estable como user_id o team_id. El denominador y cada etapa posterior deben utilizar el mismo tema.

2. Registre una forma de evento consistente

npm install telemetry-sh
import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

await telemetry.log("product_events", {
  event_name: "signup_completed",
  user_id: user.id,
  team_id: team.id,
  acquisition_channel: "docs",
  plan: "free",
});

Registre hitos posteriores en la misma tabla product_events con los mismos identificadores y campos de segmentación:

await telemetry.log("product_events", {
  event_name: "first_event_received",
  user_id: user.id,
  team_id: team.id,
  acquisition_channel: user.acquisitionChannel,
  plan: team.plan,
});

Telemetry agrega timestamp_utc automáticamente. Evite registrar correos electrónicos, nombres, cookies o contenido de solicitudes sin procesar cuando un identificador interno estable sea suficiente.

3. Calcule el embudo en una consulta.

La siguiente consulta asigna una fila por usuario, registra si ocurrió cada etapa y luego calcula los recuentos y la conversión de la cohorte de registro original.

WITH user_funnel AS (
  SELECT
    user_id,
    MIN(CASE WHEN event_name = 'signup_completed' THEN timestamp_utc END)
      AS signed_up_at,
    MIN(CASE WHEN event_name = 'workspace_created' THEN timestamp_utc END)
      AS workspace_created_at,
    MIN(CASE WHEN event_name = 'first_event_received' THEN timestamp_utc END)
      AS first_event_at,
    MIN(CASE WHEN event_name = 'dashboard_created' THEN timestamp_utc END)
      AS dashboard_created_at
  FROM product_events
  WHERE timestamp_utc >= now() - INTERVAL '30 days'
    AND event_name IN (
      'signup_completed',
      'workspace_created',
      'first_event_received',
      'dashboard_created'
    )
  GROUP BY user_id
),
stage_counts AS (
  SELECT 1 AS step, 'Signed up' AS stage, COUNT(*) AS users
  FROM user_funnel
  WHERE signed_up_at IS NOT NULL

  UNION ALL

  SELECT 2, 'Created workspace', COUNT(*)
  FROM user_funnel
  WHERE workspace_created_at >= signed_up_at

  UNION ALL

  SELECT 3, 'Sent first event', COUNT(*)
  FROM user_funnel
  WHERE first_event_at >= workspace_created_at

  UNION ALL

  SELECT 4, 'Created dashboard', COUNT(*)
  FROM user_funnel
  WHERE dashboard_created_at >= first_event_at
)
SELECT
  step,
  stage,
  users,
  ROUND(
    100.0 * users /
    NULLIF(MAX(CASE WHEN step = 1 THEN users END) OVER (), 0),
    2
  ) AS conversion_from_signup_pct,
  ROUND(
    100.0 * users /
    NULLIF(LAG(users) OVER (ORDER BY step), 0),
    2
  ) AS conversion_from_previous_pct
FROM stage_counts
ORDER BY step;

La primera etapa no tiene una tasa de etapa anterior, por lo que conversion_from_previous_pct es nulo para esa fila. Cada fila posterior muestra tanto la conversión total desde el registro como la conversión de pasos adyacentes.

4. Segmentar sin cambiar la definición

Para comparar planes o canales de adquisición, conserve el campo en el evento de registro, agréguelo a user_funnel y agrupe los recuentos de etapas por ese campo. No cambie silenciosamente el denominador de usuarios a eventos.

Las comprobaciones de segmentos útiles incluyen:

  • canal de adquisición;
  • plan u oferta inicial;
  • dispositivo o superficie de aplicación;
  • semana de inscripción;
  • La asignación del experimento se registra antes del resultado.

Evite dimensiones de alta cardinalidad hasta que el embudo no dividido sea confiable.

5. Visualiza y valida el resultado.

Utilice un gráfico de barras horizontales para users ordenado por step y muestre ambas columnas de tasas en una tabla de resultados. Antes de compartir el gráfico, inspeccione:

  • usuarios que completan una etapa posterior antes de una marca de tiempo anterior;
  • identificadores faltantes o reutilizados;
  • cuentas internas, de prueba y de bot;
  • eventos que llegaron tarde;
  • usuarios cuyo registro se produjo antes de la ventana seleccionada;
  • si la cohorte más nueva ha tenido tiempo suficiente para convertirse.

Un embudo es una medida de cohorte, no simplemente dos recuentos de eventos independientes. Para períodos de conversión más largos, incluya a los usuarios por fecha de registro y permita un período de observación fijo.

Próximos pasos

Abra el embudo de activación de registro receta SQL completo para ver un resultado de ejemplo y una visualización. Utilice retención de cohorte semanal una vez definida la activación, luego compare adopción de funciones antes de la actualización.

Función relacionada

Ejecute DataFusion SQL de solo lectura sobre tablas de eventos estructurados y reutilice el resultado.

Autores de la página y referencias

El equipo editorial de Telemetry es responsable de esta explicación; el equipo de producto revisa el comportamiento, los ejemplos y las limitaciones.

Cómo revisamos nuestra documentación