ログ SDK

@parallelsandbox/log は小さなブラウザ SDK です。ボックス内（または他の場所）で動かすページに付ければ、そのエラーとログはあなたのログプロジェクトに届きます。エージェントはコンソール出力を貼ってもらう代わりに、logs_search、logs_errors、logs_tail で読みます。

プロジェクトとキー

ログプロジェクトはテナントの API キーを使って POST https://log.parallelsandbox.com/v1/projects で作ります：

curl -fsS -X POST https://log.parallelsandbox.com/v1/projects \
  -H "Authorization: Bearer psbx_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "example-web", "origins": ["http://localhost:8080"] }'

レスポンスにプロジェクト id と write key が含まれます。各プロジェクトには次があります。

• プロジェクト id、prj_...。すべてのクエリで使います。
• write key、pw_...。ブラウザがバッチごとに送ります。このプロジェクトにしか書けないので、ページに置いても安全です。
• オリジン許可リスト。他のオリジンからのバッチは拒否されます。
• キーごとのレート制限。

プロジェクトごとに独立したロググループがあり、ログは期限なく保持されます。

インストール

バンドラーを使うなら npm から：

npm install @parallelsandbox/log

バンドラーなしなら import map で：

<script type="importmap">
{ "imports": { "@parallelsandbox/log": "https://cdn.jsdelivr.net/npm/@parallelsandbox/log/+esm" } }
</script>

初期化

import { init } from '@parallelsandbox/log';

init({
  project: 'prj_...',                          // プロジェクト id
  writeKey: 'pw_...',                          // write key
  endpoint: 'https://log.parallelsandbox.com', // ログサーバー
  release: 'a1b2c3d',                          // ビルド id。ソースマップをアップロードしたときの release と一致させる
});

できるだけ早く、一度だけ呼びます。init の後：

• 未捕捉のエラー（window.onerror）、未処理の promise rejection、console.error がスタック付きで捕捉されます。
• エントリは数秒ごとと、ページが隠れたときにまとめて送られます。
• すべてのエントリに release、ページ URL、ユーザーエージェントが付き、ページがボックスから配信されている場合はボックス id も付くので、logs_errors を boxId で絞れます。

手動呼び出し

import { log, captureError, flush } from '@parallelsandbox/log';

log('info', 'checkout started', { cart: 3 });
log('warn', 'slow response', { ms: 2400 });

try {
  riskyThing();
} catch (err) {
  captureError(err, { step: 'riskyThing' });
}

await flush(); // テストでページを離れる前に

level は info、warn、error。extra は JSON 化できる任意のオブジェクトで、logs_search で検索できます。

ソースマップ

minify されたスタックはエージェントには役に立ちません。各ビルドのソースマップを、init に渡したのと同じ release でアップロードすると、logs_errors は元のファイルと行に解決されたスタックを返します。

curl -fsS -X POST https://log.parallelsandbox.com/v1/projects/prj_.../sourcemaps \
  -H "Authorization: Bearer psbx_YOUR_API_KEY" \
  -F "release=a1b2c3d" \
  -F "path=assets/app-ALQGRFWG.js" \
  -F "map=@dist/assets/app-ALQGRFWG.js.map;type=application/json"

マップ 1 つにつき 1 リクエスト。path はスタックに現れるスクリプトのパス（ページのオリジンからの相対）です。アップロードには write key ではなくテナントの API キーを使います。example-web-with-logs には dist/ 全体をアップロードするスクリプトがあります。

エージェントから問い合わせる

logs_errors { "project": "prj_...", "since": "30m", "boxId": "<box id>" }
logs_search { "project": "prj_...", "since": "1h", "query": "checkout" }
logs_tail   { "project": "prj_...", "boxId": "<box id>" }

各行には ts、level、message、release、url、boxId、extra があり、エラーには stack と stackResolved も付きます。

コスト

ログの取り込みと保持も他の使用量と同様に、原価の 1.5 倍で計量されます。

1 日に数百件のエラーを報告するページでも、月に 1 クレジットに届きません。