Guida rapida a Signals

In questa pagina aggiungi l'SDK di Signals a un'app, scegli dove vanno i suoi eventi e segnali gli errori e gli eventi che Signals raggruppa e verifica. L'SDK è lo stesso in ogni modalità: cambia solo la destinazione.

Aggiungi l'SDK

npm install @pathrule/signals

L'SDK è @pathrule/signals, con licenza Apache-2.0. Funziona su Node 18 o versioni successive e nei browser attuali (ES2022 e fetch). Il suo pacchetto npm pubblico è in fase di pubblicazione, quindi controlla lo stato nella panoramica.

Inizializzalo

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 vale development, preview o production.

Scegli una destinazione

Standalone, con il tuo collector. httpCollector({ url, headers?, credentials? }) invia gli envelope tramite POST a qualsiasi endpoint che parli il protocollo Signals. Non serve alcun account Pathrule.

Pathrule Local. Crea una sola volta un workspace locale nel progetto, poi invia gli eventi all'host Pathrule sulla tua macchina. Questa destinazione funziona solo con 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 chiave di progetto e passala alla destinazione Cloud. Le chiavi iniziano con prs_, sono in sola scrittura e si possono includere senza rischi nel codice client. Per la gestione delle chiavi consulta Cloud Signals.

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

Una destinazione personalizzata è qualsiasi oggetto che implementa SignalsDestination.

Segnala errori ed eventi

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

Il secondo argomento è il collegamento: node è il percorso di codice a cui appartiene l'evento, flow indica il flusso visibile all'utente, text aggiunge una breve descrizione e meta contiene i dettagli. Un evento con meta.outcome: "success" sul flusso di un gruppo è la prova che permette di verificare una correzione per quel gruppo.

Imposta la release

release è una stringa di versione, un oggetto con version, commit e deployment, oppure null. releaseFromEnvironment(process.env) la ricava dalle variabili di deployment più comuni. Senza un'identità di release Signals può comunque raggruppare gli eventi, ma non può verificare una correzione: pathrule.status().verification riporta no_release.

Esegui il flush prima che un processo termini

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

La promise di flush() non viene mai rifiutata. Il suo timeout è di 5 secondi per impostazione predefinita, con un massimo di 30. Nei browser l'SDK invia ciò che è in sospeso con sendBeacon quando la pagina viene chiusa, mentre in Node esegue il flush su beforeExit. Chiamala tu stesso nei processi di breve durata, come le funzioni serverless.

Configurazione

pathrule.status() indica se la verifica è ready, no_release o inactive, e pathrule.reset() azzera il client.