Guía rápida de Signals

En esta página agregarás el SDK de Signals a una app, elegirás a dónde van sus eventos y reportarás los errores y eventos que Signals agrupa y verifica. El SDK es el mismo en todos los modos; solo cambia el destino.

Agrega el SDK

npm install @pathrule/signals

El SDK es @pathrule/signals, con licencia Apache-2.0. Funciona en Node 18 o posterior y en navegadores actuales (ES2022 y fetch). Su paquete público de npm está en proceso de publicación, así que consulta su estado en la descripción general.

Inicialízalo

import { pathrule, httpCollector } from "@pathrule/signals";

pathrule.init({
  destination: httpCollector({
    url: "https://collector.example.com/signals",
    headers: { Authorization: `Bearer ${process.env.SIGNALS_TOKEN}` },
  }),
  environment: "production",
  release: { version: "2.4.0", commit: process.env.GIT_SHA },
});

environment puede ser development, preview o production.

Elige un destino

Standalone, con tu propio colector. httpCollector({ url, headers?, credentials? }) envía los sobres a cualquier endpoint que hable el protocolo de Signals. No interviene ninguna cuenta de Pathrule.

Pathrule Local. Crea un espacio de trabajo local una sola vez en el proyecto y luego envía los eventos al host de Pathrule en tu máquina. Este destino solo funciona en Node.

pathrule init --local

import { pathrule } from "@pathrule/signals";
import { pathruleLocal } from "@pathrule/signals/local";

pathrule.init({ destination: pathruleLocal(), environment: "development", release: "2.4.0" });

Pathrule Cloud. Crea una clave de proyecto y pásala al destino de Cloud. Las claves empiezan con prs_, son de solo escritura y se pueden incluir sin riesgo en el código del cliente. Consulta Cloud Signals para administrar las claves.

import { pathrule, pathruleCloud } from "@pathrule/signals";

pathrule.init({
  destination: pathruleCloud({ key: process.env.PATHRULE_SIGNALS_KEY }),
  environment: "production",
  release: { version: "2.4.0", commit: process.env.GIT_SHA },
});

Un destino personalizado es cualquier objeto que implemente SignalsDestination.

Reporta errores y eventos

try {
  await submitOrder(cart);
  pathrule.event("order placed", {
    node: "/apps/web/checkout",
    flow: "checkout",
    meta: { outcome: "success" },
  });
} catch (error) {
  pathrule.error(error, { node: "/apps/web/checkout", flow: "checkout" });
  throw error;
}

El segundo argumento es el vínculo: node es la ruta de código a la que pertenece el evento, flow nombra el flujo visible para el usuario, text agrega una descripción breve y meta lleva los detalles. Un evento con meta.outcome: "success" en el flujo de un grupo es la evidencia que permite verificar una corrección de ese grupo.

Define el release

release es una cadena de versión, un objeto con version, commit y deployment, o null. releaseFromEnvironment(process.env) lo lee de las variables de despliegue más comunes. Sin una identidad de release, Signals igual puede agrupar eventos, pero no puede verificar una corrección: pathrule.status().verification reporta no_release.

Vacía la cola antes de que termine el proceso

const result = await pathrule.flush({ timeoutMs: 5000 });
// result: { outcome, delivered, pending, dropped }

La promesa de flush() nunca se rechaza. Su tiempo de espera es de 5 segundos por defecto, con un máximo de 30. En navegadores, el SDK envía lo pendiente con sendBeacon cuando se descarga la página, y en Node vacía la cola en beforeExit. Llámalo tú mismo en procesos de corta duración, como las funciones serverless.

Configuración

pathrule.status() indica si la verificación está en ready, no_release o inactive, y pathrule.reset() reinicia el cliente.