Guia rápido do Signals

Esta página adiciona o SDK do Signals a um app, define para onde vão os eventos e reporta os erros e eventos que o Signals agrupa e verifica. O SDK é o mesmo em todos os modos; só o destino muda.

Adicione o SDK

npm install @pathrule/signals

O SDK é o @pathrule/signals, sob licença Apache-2.0. Ele roda no Node 18 ou superior e em navegadores atuais (ES2022 e fetch). O pacote público no npm está em processo de publicação, então confira o status na visão geral.

Inicialize o SDK

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 aceita development, preview ou production.

Escolha um destino

Standalone, com seu próprio coletor. httpCollector({ url, headers?, credentials? }) envia envelopes via POST para qualquer endpoint que implemente o protocolo do Signals. Nenhuma conta do Pathrule é necessária.

Pathrule Local. Crie uma única vez um espaço de trabalho local no projeto e depois envie os eventos para o host do Pathrule na sua máquina. Este destino funciona apenas no 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. Crie uma chave de projeto e passe-a para o destino do Cloud. As chaves começam com prs_, são somente de escrita e podem ser incluídas com segurança no código do cliente. Veja Cloud Signals para saber como gerenciar as chaves.

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 },
});

Um destino personalizado é qualquer objeto que implemente SignalsDestination.

Reporte erros e 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;
}

O segundo argumento é o vínculo: node é o caminho de código a que o evento pertence, flow nomeia o fluxo visível para o usuário, text adiciona uma descrição curta e meta traz os detalhes. Um evento com meta.outcome: "success" no fluxo de um grupo é a evidência que permite verificar uma correção feita nesse grupo.

Defina a release

release é uma string de versão, um objeto com version, commit e deployment, ou null. releaseFromEnvironment(process.env) lê esse valor das variáveis de deploy mais comuns. Sem uma identidade de release, o Signals ainda consegue agrupar eventos, mas não consegue verificar uma correção: pathrule.status().verification reporta no_release.

Faça o flush antes de o processo encerrar

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

A promise de flush() nunca é rejeitada. O timeout padrão é de 5 segundos, com máximo de 30. Nos navegadores, o SDK envia o que estiver pendente com sendBeacon quando a página é descarregada; no Node, ele faz o flush no beforeExit. Em processos de curta duração, como funções serverless, chame-o você mesmo.

Configuração

pathrule.status() informa se a verificação está ready, no_release ou inactive, e pathrule.reset() limpa o cliente.