@ah-monica/cloudflare 0.3.0 → 0.4.0

package/README.md

@@ -44,7 +44,7 @@ function createClient(env: Env) {
 ブラウザ側の SDK にも同じ値を渡すと、Worker とブラウザの event が同じ release に揃う。
 
 DSN を Secrets Store に置く場合、binding の値は `get()` で非同期に読むので、client は
-`catch` の中で作る（[制約](#制約) のとおり request ごとに作ってよい）。`get()` は secret が
+request の入口で作る（[制約](#制約) のとおり request ごとに作ってよい）。`get()` は secret が
 無いと例外を投げるので、`undefined` に落として何も送らない client にする。
 
 ```ts
@@ -56,14 +56,15 @@ interface Env {
 
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const monica = createCloudflareClient({
+      dsn: await env.MONICA_DSN.get().catch(() => undefined),
+      environment: env.MONICA_ENVIRONMENT,
+      release: env.MONICA_RELEASE,
+    });
+    ctx.waitUntil(monica.flush());
     try {
       return await handleRequest(request, env);
     } catch (error) {
-      const monica = createCloudflareClient({
-        dsn: await env.MONICA_DSN.get().catch(() => undefined),
-        environment: env.MONICA_ENVIRONMENT,
-        release: env.MONICA_RELEASE,
-      });
       monica.captureExceptionInBackground(ctx, error);
       return new Response("Internal Server Error", { status: 500 });
     }
@@ -73,6 +74,8 @@ export default {
 
 ## 使い方
 
+request の入口で client を作り、`ctx.waitUntil(monica.flush())` を呼ぶ（[稼働確認](#稼働確認)）。
+
 `captureException()` は capture と flush の両方を終えてから解決する Promise を返す。
 handler の応答を待たせたくない場合は `captureExceptionInBackground(ctx, ...)` で
 `ExecutionContext.waitUntil()` に載せる。
@@ -80,10 +83,12 @@ handler の応答を待たせたくない場合は `captureExceptionInBackground
 ```ts
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const monica = createClient(env);
+    ctx.waitUntil(monica.flush());
     try {
       return await handleRequest(request, env);
     } catch (error) {
-      createClient(env).captureExceptionInBackground(ctx, error, {
+      monica.captureExceptionInBackground(ctx, error, {
         tags: { operation: "handle-request" },
         // URL の path にも個人情報が入り得るので、安全と判断した値だけを渡す。
         request: { method: request.method, url: new URL(request.url).origin },
@@ -108,6 +113,16 @@ await monica.captureException(error, { tags: { trigger: "scheduled" } });
 Worker の外側で起きた未捕捉例外まで集めたい場合は Tail Worker も検討する。この adapter は、
 アプリケーションが捕捉して業務上の文脈を選んで送る例外を対象にする。
 
+## 稼働確認
+
+共通の仕組みは [ルートの README](../README.md#稼働確認) にある。
+
+- isolate で最初の `flush()` / `captureException()` / `captureMessage()` の呼び出しが
+  `trigger: "start"` を 1 通送る。client を作っただけでは送らない。`dsn` と `environment` の組ごとに数える
+- request の入口で `ctx.waitUntil(monica.flush())` を呼ぶ。`waitUntil` が無いと handler の終了で送信が打ち切られる
+- Workers にはタイマーが無いので `trigger: "interval"` は送らない。isolate が作り直されるたびに `start` を送る
+- 状態は isolate のメモリに持ち、ストレージには書かない
+
 ## オプション
 
 | option | 型 | default | 説明 |

package/dist/client.js

@@ -3,6 +3,10 @@ import { SDK_VERSION } from "./version.js";
 const DEFAULT_FLUSH_TIMEOUT_MS = 2_000;
 const DEFAULT_MAX_CAUSE_DEPTH = 10;
 const DEFAULT_MAX_STACK_FRAMES = 200;
+// client は request ごとに作られるので、start を送ったかは isolate に 1 つ持つ。
+// 判定の前に印を付けるので、並行する request でも isolate ごとに 1 回になる
+// （dsn と environment が違えば別に数える）
+const startedInIsolate = new Set();
 export function createCloudflareClient(options) {
     assertPositiveInteger("flushTimeoutMs", options.flushTimeoutMs);
     assertPositiveInteger("maxCauseDepth", options.maxCauseDepth);
@@ -10,6 +14,7 @@ export function createCloudflareClient(options) {
     const flushTimeoutMs = options.flushTimeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS;
     const maxCauseDepth = options.maxCauseDepth ?? DEFAULT_MAX_CAUSE_DEPTH;
     const maxStackFrames = options.maxStackFrames ?? DEFAULT_MAX_STACK_FRAMES;
+    const presenceKey = `${options.dsn ?? ""}\n${options.environment}`;
     const core = createCoreClient({
         transport: createFetchTransport({
             dsn: options.dsn,
@@ -24,12 +29,28 @@ export function createCloudflareClient(options) {
         sampleRate: options.sampleRate,
         beforeSend: options.beforeSend,
         sdk: { name: "@ah-monica/cloudflare", version: SDK_VERSION },
+        presence: { platform: "javascript" },
     });
+    /**
+     * Workers にはタイマーが無く、global scope では fetch できない。生成時ではなく最初の
+     * flush / capture の呼び出し（request の中）で start を送る。送信中の分は flush() が
+     * 待つので、それを waitUntil に載せれば handler の後まで生きる。
+     */
+    function startOnce() {
+        if (startedInIsolate.has(presenceKey))
+            return;
+        startedInIsolate.add(presenceKey);
+        void core.checkPresence("start");
+    }
+    function flush(timeoutMs) {
+        startOnce();
+        return core.flush(timeoutMs);
+    }
     async function captureAndFlush(input, hint) {
         try {
+            startOnce();
             const eventId = await core.capture(input, hint);
-            if (eventId === null)
-                return null;
+            // 捨てた event でも、送信中の start は待つ
             await core.flush(flushTimeoutMs);
             return eventId;
         }
@@ -75,7 +96,7 @@ export function createCloudflareClient(options) {
         captureException,
         captureMessage,
         captureExceptionInBackground,
-        flush: core.flush,
+        flush,
         close: core.close,
     };
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** package.json の version と同じ値。bun run version X.Y.Z が書き換える */
-export declare const SDK_VERSION = "0.3.0";
+export declare const SDK_VERSION = "0.4.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** package.json の version と同じ値。bun run version X.Y.Z が書き換える */
-export const SDK_VERSION = "0.3.0";
+export const SDK_VERSION = "0.4.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ah-monica/cloudflare",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Cloudflare Workers adapter for sending application errors to MONICA",
   "license": "Apache-2.0",
   "type": "module",
@@ -32,7 +32,7 @@
     "directory": "cloudflare"
   },
   "dependencies": {
-    "@ah-monica/core": "0.3.0"
+    "@ah-monica/core": "0.4.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.21",