Démarrage rapide avec Signals

Cette page explique comment ajouter le SDK Signals à une application, choisir où partent ses événements et remonter les erreurs et les événements que Signals regroupe et vérifie. Le SDK est le même dans tous les modes ; seule la destination change.

Ajouter le SDK

npm install @pathrule/signals

Le SDK s'appelle @pathrule/signals et est distribué sous licence Apache-2.0. Il fonctionne sur Node 18 ou version ultérieure et dans les navigateurs actuels (ES2022 et fetch). Son package npm public est en cours de publication : consultez la présentation pour connaître son état.

L'initialiser

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

Choisir une destination

Standalone, avec votre propre collecteur. httpCollector({ url, headers?, credentials? }) envoie les enveloppes vers n'importe quel endpoint qui implémente le protocole Signals. Aucun compte Pathrule n'est nécessaire.

Pathrule Local. Créez une fois un espace de travail local dans le projet, puis envoyez les événements vers l'hôte Pathrule de votre machine. Cette destination ne fonctionne qu'avec 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. Créez une clé de projet et passez-la à la destination Cloud. Les clés commencent par prs_, sont en écriture seule et peuvent être incluses sans risque dans le code client. Consultez Cloud Signals pour la gestion des clés.

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

Une destination personnalisée est simplement un objet qui implémente SignalsDestination.

Remonter les erreurs et les événements

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

Le second argument est le rattachement : node est le chemin de code auquel appartient l'événement, flow nomme le flux visible par l'utilisateur, text ajoute une courte description et meta transporte les détails. Un événement portant meta.outcome: "success" sur le flux d'un groupe constitue la preuve qui permet de vérifier un correctif apporté à ce groupe.

Définir la release

release est une chaîne de version, un objet contenant version, commit et deployment, ou null. releaseFromEnvironment(process.env) la lit à partir des variables de déploiement courantes. Sans identité de release, Signals peut toujours regrouper les événements, mais ne peut pas vérifier un correctif : pathrule.status().verification renvoie no_release.

Vider la file avant la fin d'un processus

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

La promesse de flush() n'est jamais rejetée. Son délai d'expiration est de 5 secondes par défaut, avec un maximum de 30. Dans les navigateurs, le SDK envoie ce qui est en attente avec sendBeacon lorsque la page se ferme, et dans Node il vide la file sur beforeExit. Appelez-la vous-même dans les processus de courte durée, comme les fonctions serverless.

Configuration

pathrule.status() indique si la vérification est ready, no_release ou inactive, et pathrule.reset() réinitialise le client.