本文へスキップ
Pathrule

pathrule.iodocs

Pathrule

ドキュメント

ドキュメントはじめる

プロトコルとコレクター

コレクターが受け取るSignalsプロトコル（エンベロープ、アイテム、サイズ上限）、SDKによるコレクターのレスポンスの解釈と再試行、Standaloneモードで独自のHTTPコレクターを運用する方法を説明します。

このページの内容

Standaloneモードでは、SDKは自分で運用するHTTPコレクターに送信します。このページでは、コレクターが何を受け取り、どう応答すべきかを説明します。Pathrule LocalとPathrule Cloudも同じプロトコルを使うため、送信先を切り替えてもここに書かれた内容は変わりません。

エンベロープ

プロトコルのバージョンは1です。SDKは1回のPOSTにつきエンベロープを1つ、application/jsonとして送信します。ページのアンロード中に送られるビーコンはtext/plainを使います。エンベロープのサイズは最大32,768バイトで、含められるアイテムは最大50件です。

フィールド内容
schemaVersionプロトコルのバージョン。
id英字、数字、_、-からなる最大64文字。再試行のたびに同じ値になるため、コレクターはエンベロープを一度だけ保存できます。
keyプロジェクトキー。Cloudでのみ使用します。
environmentdevelopment、preview、productionのいずれか。
releaseリリースの識別子。最大120文字。
connectionSDKの接続方法。
itemsこのエンベロープに含まれるシグナルと宣言。

各アイテムはtype（signalまたはdeclaration）、kind（errorまたはevent）、fingerprint、countDelta、node（コードパス）、flow、label、message、metadataを持ちます。同じ事象が繰り返し発生した場合はcountDeltaに合算されるため、コレクターはアイテムの件数ではなくこの値で集計します。

レスポンスと再試行

レスポンスSDKの動作
2xx配信済みとして扱います。
401、403送信を完全に停止します。
408、429、5xx再試行します。
その他の4xxバッチを破棄します。

再試行は1分後、5分後、15分後に行われ、試行は最大4回です。SDKが送信待ちとして保持するエンベロープは最大20件です。Retry-Afterヘッダーは秒数として解釈されます。

独自のコレクターを運用する

コレクターの役割は3つです。リクエストの認証、エンベロープの検証、そして保存または転送です。

import { normalizeEnvelope } from "@pathrule/signals/protocol";

// In your POST handler, after checking your own Authorization header:
const envelope = normalizeEnvelope(body, { requireKey: false, bytes: rawBody.length });

クイックスタートのBearerヘッダーのように別の方法で認証する場合はrequireKey: falseを渡します。また、サイズ上限が適用されるよう、生のサイズも渡してください。そのうえで、次の点を守ります。

  • エンベロープはidごとに一度だけ保存します。再試行では同じ値が使われます。
  • アイテムはPathruleと同じく、environment、kind、fingerprintの単位でグループ化します。
  • エンベロープを安全に保存できた時点ですぐに2xxを返し、401や403はクライアントに送信を停止させたい場合にのみ返します。