Signals quickstart

This page adds the Signals SDK to an app, picks where its events go, and reports the errors and events that Signals groups and verifies. The SDK is the same in every mode; only the destination changes.

Add the SDK

npm install @pathrule/signals

The SDK is @pathrule/signals, licensed Apache-2.0. It runs on Node 18 or later and in current browsers (ES2022 and fetch).

Initialize it

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 is development, preview or production.

Choose a destination

Standalone, your own collector. httpCollector({ url, headers?, credentials? }) posts envelopes to any endpoint that speaks the Signals protocol. No Pathrule account is involved.

Pathrule Local. Create a local workspace once in the project, then send events to the Pathrule host on your machine. This destination is Node only.

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. Create a project key on the workspace's Signals page in the Pathrule Cloud console and pass it to the Cloud destination. Keys start with prs_, are write-only and are safe to ship in client code. See Cloud Signals for key management.

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

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

A custom destination is any object that implements SignalsDestination.

Report errors and events

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

The second argument is a link: node is the code path the event belongs to, flow names the user-visible flow, text adds a short description and meta carries details. An event with meta.outcome: "success" on a group's flow is the evidence that lets a fix to that group be verified.

Set the release

release is a version string, an object with version, commit and deployment, or null. releaseFromEnvironment(process.env) reads it from common deployment variables. Without a release identity Signals can still group events, but it cannot verify a fix: pathrule.status().verification reports no_release.

Flush before a process exits

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

flush() never rejects. Its timeout defaults to 5 seconds, with a maximum of 30. In browsers the SDK sends what is pending with sendBeacon when the page unloads, and in Node it flushes on beforeExit. Call it yourself in short-lived processes such as serverless functions.

Configuration

pathrule.status() reports whether verification is ready, no_release or inactive, and pathrule.reset() clears the client.