@belvador/cloudflare 0.2.0 → 0.3.0

package/README.md

@@ -30,8 +30,9 @@ response (status, headers, streamed body) is returned unchanged and sending fini
 
 ## What it sends
 
-Errors only (exceptions, messages, breadcrumbs you turn on, attachments if you enable them).
-No tracing, session replay, logs or profiling — those items are dropped inside your app.
+Errors (exceptions, messages, breadcrumbs you turn on, attachments if you enable them) and
+the job check-ins you send with `withMonitor`. No spans, session replay, logs or profiling —
+those items are dropped inside your app.
 
 Before anything leaves your app the SDK removes `Authorization`, `Cookie` and `Set-Cookie`
 headers, request bodies and cookies, client IP headers, and masks credentials in URLs, query
@@ -44,6 +45,40 @@ each attempt times out after 10 s, failed sends retry at most 5 times, `429` rat
 respected, and a revoked key (`401`/`403`) stops sending for the life of the page or isolate.
 Every public function catches its own errors.
 
+## Monitor background work
+
+Errors alone cannot tell you that a job never ran. Wrap scheduled and queued work in
+`withMonitor` (Sentry-compatible check-ins): Belvador sees each run start and finish, and
+opens an incident when a run fails, times out or never happens.
+
+```ts
+import { withMonitor } from "@belvador/cloudflare";
+
+export default withBelvador((env) => ({ release: env.BELVADOR_RELEASE }), {
+  async scheduled(controller, env, ctx) {
+    await withMonitor("nightly-invoices", async (run) => {
+      const due = await loadDueInvoices(env);
+      if (due.length === 0) return run.skip("nothing_due");
+      await sendInvoices(env, due);
+    }, { schedule: { type: "crontab", value: "0 2 * * *" }, timezone: "Europe/Berlin" });
+  },
+});
+```
+
+Your function's result and errors come back unchanged (a synchronous function stays
+synchronous); an error is also reported as a normal issue with the monitor's slug. For queue
+consumers pass `runId` (your message id), `attempt` and `willRetry` so retries count as one
+run. `captureCheckIn()` and `heartbeat()` cover manual start/finish and "still alive" checks.
+Check-ins are sent only from server code. See https://belvador.dev/docs/monitors/setup
+
+## Link requests with one trace
+
+Off by default. `tracePropagation: { targets: ["https://api.example.com"] }` adds
+`traceparent` and `sentry-trace` headers to `fetch` calls to those URLs, so an error in the
+called service and its job check-ins show up with the same trace id. An incoming
+`traceparent` (or `sentry-trace`) is continued. No spans or transactions are sent; `baggage`
+only with `baggage: true`. See https://belvador.dev/docs/sdk/tracing
+
 ## Check the connection
 
 "No errors" is not proof that errors arrive. Call `verifyIntegration()` from `@belvador/cloudflare` inside a request handled by `withBelvador`:

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { CloudflareOptions as EngineCloudflareOptions } from "@sentry/cloudflare";
 import { type BelvadorOptions, type VerificationResult, type VerifyOptions } from "@belvador/core";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, type Scope, type SeverityLevel, type VerificationResult, type VerifyOptions, } from "@belvador/core";
+export { SDK_VERSION, addBreadcrumb, captureCheckIn, captureException, captureMessage, close, flush, heartbeat, withMonitor, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type CheckInInput, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, type MonitorConfigInput, type MonitorSchedule, type RunHandle, type Scope, type SeverityLevel, type TracePropagationOptions, type VerificationResult, type VerifyOptions, type WithMonitorOptions, } from "@belvador/core";
 export type WorkerOptions = Omit<BelvadorOptions, "dsn"> & {
     /** Defaults to the BELVADOR_DSN binding. */
     dsn?: string;

package/dist/index.js

@@ -3,8 +3,8 @@
 // privacy and sending rules. Needs the `nodejs_compat` (or `nodejs_als`)
 // compatibility flag so every request gets its own scope.
 import { consoleIntegration, dedupeIntegration, eventFiltersIntegration, fetchIntegration, linkedErrorsIntegration, requestDataIntegration, withSentry, } from "@sentry/cloudflare";
-import { buildEngineOptions, currentHooks, markHooked, noteClientAbort, runVerification, } from "@belvador/core";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "@belvador/core";
+import { TRACE_OPTION, buildEngineOptions, currentHooks, installTracePropagation, markHooked, noteClientAbort, runVerification, withIncomingTraceparent, } from "@belvador/core";
+export { SDK_VERSION, addBreadcrumb, captureCheckIn, captureException, captureMessage, close, flush, heartbeat, withMonitor, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "@belvador/core";
 function binding(env, name) {
     if (env === null || typeof env !== "object")
         return undefined;
@@ -76,8 +76,11 @@ export function workerEngineOptions(options, env, runtime = "cloudflare") {
         ];
         if (o.instrument?.console === true)
             integrations.push(consoleIntegration());
+        // Breadcrumbs only: trace headers come from Belvador's own hook, never the engine's.
         if (o.instrument?.fetch === true)
-            integrations.push(fetchIntegration({ breadcrumbs: true }));
+            integrations.push(fetchIntegration({ breadcrumbs: true, shouldCreateSpanForRequest: () => false }));
+        if (base[TRACE_OPTION])
+            installTracePropagation();
         return {
             ...base,
             // 0, not undefined: an undefined value would let SENTRY_TRACES_SAMPLE_RATE turn tracing on.
@@ -140,7 +143,7 @@ function isThenable(value) {
 }
 /** Shared with @belvador/tanstack-start so its server events carry its own SDK name. */
 export function wrapHandler(optionsCallback, handler, runtime) {
-    return withSentry((env) => {
+    const wrapped = withSentry((env) => {
         let options;
         try {
             options = optionsCallback(env);
@@ -150,6 +153,24 @@ export function wrapHandler(optionsCallback, handler, runtime) {
         }
         return workerEngineOptions(options, env, runtime);
     }, marked(handler));
+    return incomingTrace(wrapped);
+}
+/**
+ * Spec 06 §5: an incoming W3C `traceparent` (without `sentry-trace`) continues the same
+ * trace; the request is otherwise passed through untouched.
+ */
+function incomingTrace(handler) {
+    if (handler === null || typeof handler !== "object")
+        return handler;
+    const fetch = handler["fetch"];
+    if (typeof fetch !== "function")
+        return handler;
+    return {
+        ...handler,
+        fetch(request, ...rest) {
+            return fetch.call(handler, withIncomingTraceparent(request), ...rest);
+        },
+    };
 }
 /**
  * Wraps a Worker's exported handler (fetch, scheduled, queue, email, tail):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/cloudflare",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Belvador error tracking for Cloudflare Workers: per-request scope, errors only, private by default.",
   "license": "MIT",
   "author": "Belvador (https://belvador.dev)",
@@ -32,7 +32,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@belvador/core": "0.2.0",
+    "@belvador/core": "0.3.0",
     "@sentry/cloudflare": "10.76.2"
   },
   "publishConfig": {