Signalsクイックスタート

このページでは、アプリにSignals SDKを追加し、イベントの送信先を決め、Signalsがグループ化して検証するエラーとイベントを報告するまでを説明します。SDKはどのモードでも同じで、変わるのは送信先だけです。

SDKの追加

npm install @pathrule/signals

SDKは@pathrule/signalsで、ライセンスはApache-2.0です。Node 18以降と現行ブラウザ（ES2022とfetchに対応）で動作します。npmパッケージは公開準備中のため、状況は概要で確認してください。

初期化

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にはdevelopment、preview、productionのいずれかを指定します。

送信先の選択

Standalone（独自のコレクター）。 httpCollector({ url, headers?, credentials? })は、Signalsプロトコルに対応した任意のエンドポイントへエンベロープをPOSTします。Pathruleアカウントは必要ありません。

Pathrule Local。 プロジェクトで一度ローカルワークスペースを作成し、手元のマシン上のPathruleホストへイベントを送信します。この送信先は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。 プロジェクトキーを作成し、Cloudの送信先に渡します。キーはprs_で始まり、書き込み専用なので、クライアントコードに含めて配布しても安全です。キーの管理については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 },
});

SignalsDestinationを実装したオブジェクトであれば、独自の送信先として使えます。

エラーとイベントの報告

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

第2引数は紐づけ情報です。nodeはイベントが属するコードパス、flowはユーザーから見えるフローの名前、textは短い説明、metaは詳細情報を表します。グループのフロー上でmeta.outcome: "success"を持つイベントが、そのグループに対する修正を検証するための根拠になります。

リリースの設定

releaseには、バージョン文字列、version、commit、deploymentを持つオブジェクト、またはnullを指定します。releaseFromEnvironment(process.env)を使うと、一般的なデプロイ用の環境変数から読み取れます。リリース情報がなくてもSignalsはイベントをグループ化できますが、修正の検証はできません。その場合、pathrule.status().verificationはno_releaseを報告します。

プロセス終了前のフラッシュ

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

flush()のPromiseがrejectされることはありません。タイムアウトはデフォルトで5秒、最大30秒です。ブラウザではページのアンロード時にsendBeaconで未送信分を送信し、NodeではbeforeExitでフラッシュします。サーバーレス関数のような短命なプロセスでは、自分で呼び出してください。

設定

pathrule.status()は検証の状態がready、no_release、inactiveのどれかを報告し、pathrule.reset()はクライアントをクリアします。