@bigbertha/sdk 0.6.1 → 0.8.0

package/README.md

@@ -3,13 +3,16 @@
 Error reporting for bertha. Browser, React, Node, edge and Next.js, with no dependencies
 and source maps matched by debug id rather than by file path.
 
-- About 5.8 kB gzipped in the browser (`npm run size` enforces the budget).
+- About 6.9 kB gzipped in the browser (`npm run size` enforces the budget).
 - Batches events, backs off when bertha says so, and sends what's queued as the page or
   process goes away.
 - Scrubs emails, bearer tokens and secret-looking query values by default.
 - Each event says how it surfaced (an uncaught error, a rejection, a boundary, a call),
   where (the page or request) and in what state, and links the page's requests to the
   server errors they caused by W3C `traceparent`.
+- Works with OpenTelemetry: `otlp()` points an OTel exporter at bertha, an error inside
+  an active span is recorded on it, and the browser sends its page's requests as spans
+  once the page has an error. See [Traces](#traces).
 - The build plugins give each bundle a debug id, upload its map and delete the `.map`
   files, so maps never ship to browsers.
 
@@ -110,6 +113,11 @@ export default defineConfig({ plugins: [bertha()] })
   init({ key, url, tracePropagationTargets: ["https://api.example.com"] })
   ```
 
+- **The page's requests as spans:** the page itself, its document load and each fetch
+  and XHR with its method, scrubbed URL and status. They wait in memory (the last 200)
+  and go to bertha only once the page has had an error, then for as long as it stays
+  open, so a page that never errors sends none. `spans: false` turns it off.
+
 Frames in browser extensions and in scripts Safari hides (`webkit-masked-url://`) are
 sent as not the app's code, so bertha can say when an error probably isn't yours.
 
@@ -184,6 +192,48 @@ For bundled Node code, give the output debug ids and upload its maps after the b
 npx bertha sourcemaps upload dist
 ```
 
+## Traces
+
+bertha takes OpenTelemetry traces over OTLP/HTTP, so an error's page shows what the
+whole request did across your services: where the time went, what failed first, and
+calls into a service that never answered. It keeps spans for an hour and keeps a
+trace for good once an error event names it, so only traces with an error stay.
+
+The SDK doesn't record server spans itself. Use OpenTelemetry's own instrumentation and
+point its exporter at bertha with `otlp()`, which gives the URL and the key's header
+from `BERTHA_KEY` and `BERTHA_URL` (or `key` and `url`):
+
+```ts
+// Next.js: instrumentation.ts (npm install @vercel/otel)
+import { OTLPHttpProtoTraceExporter, registerOTel } from "@vercel/otel"
+import { otlp, register as bertha } from "@bigbertha/sdk/next"
+export { onRequestError } from "@bigbertha/sdk/next"
+
+export function register() {
+  registerOTel({ serviceName: "shop", traceExporter: new OTLPHttpProtoTraceExporter(otlp()) })
+  return bertha()
+}
+```
+
+```ts
+// Node: before anything else loads
+// (npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto)
+import { NodeSDK } from "@opentelemetry/sdk-node"
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node"
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto"
+import { init, otlp } from "@bigbertha/sdk/node"
+
+new NodeSDK({ traceExporter: new OTLPTraceExporter(otlp()), instrumentations: [getNodeAutoInstrumentations()] }).start()
+init()
+```
+
+Any other OTLP exporter works too: send to `<url>/ingest/v1/traces` with
+`Authorization: Bearer <key>`, as protobuf or JSON.
+
+With OpenTelemetry running, every event names the span that was active when it was
+captured, so bertha places the error on that span. Without it, events still carry the
+trace from an incoming `traceparent` and land on the request's outermost span.
+
 ## Edge
 
 ```ts
@@ -219,6 +269,7 @@ await flush()
 | `versions` | | More versions on every event, as `{ name: version }`. |
 | `sendIp` | `true` | Browser: store the visitor's IP. |
 | `tracePropagationTargets` | same origin only | Browser: other origins whose requests get a `traceparent`. |
+| `spans` | `true` | Browser: record the page's requests as spans and send them once the page has an error. |
 | `breadcrumbs` | all on | Browser: `fetch`, `xhr`, `navigation`, `click`, `console`. |
 | `debug` | `false` | Log what the SDK does. |
 

package/dist/browser/index.d.ts

@@ -13,6 +13,11 @@ export interface BrowserOptions extends Options {
      * must allow the header in CORS.
      */
     tracePropagationTargets?: (string | RegExp)[];
+    /**
+     * Record the page's requests as spans, and send them to the trace once the page has
+     * had an error, so its waterfall shows what the browser did. On by default.
+     */
+    spans?: boolean;
 }
 export declare function init(options: BrowserOptions): Client | undefined;
 /** What the page looked like when it failed. Called for every event. */

package/dist/browser/index.js

@@ -6,6 +6,7 @@ import { scrubUrl } from "../core/scrub.js";
 import { randomHex, traceparent } from "../core/trace.js";
 import { fetchTransport, streamGzip } from "../core/transport.js";
 import { VERSION } from "../core/version.js";
+import { spans } from "./spans.js";
 import { userAgent } from "./user-agent.js";
 export { addBreadcrumb, captureException, captureMessage, flush, getClient, setTag, setUser } from "../core/hub.js";
 let installed = false;
@@ -19,14 +20,19 @@ export function init(options) {
         return undefined;
     }
     const nativeFetch = window.fetch.bind(window);
+    const beacon = (url, body) => !!navigator.sendBeacon?.(url, new Blob([body], { type: "text/plain" }));
+    const recorder = options.spans === false ? undefined : spans({ url: options.url, key: options.key, traceId, fetch: nativeFetch, beacon });
     const client = new Client(options, fetchTransport({
         url: options.url,
         key: options.key,
         keyInQuery: true,
         gzip: streamGzip,
         fetch: nativeFetch,
-        beacon: (url, body) => !!navigator.sendBeacon?.(url, new Blob([body], { type: "text/plain" })),
-    }), { name: "bertha.browser", version: VERSION }, { ...userAgent(navigator.userAgent), userAgent: navigator.userAgent }, undefined, (event) => enrich(event, options.sendIp !== false));
+        beacon,
+    }), { name: "bertha.browser", version: VERSION }, { ...userAgent(navigator.userAgent), userAgent: navigator.userAgent }, undefined, (event) => {
+        enrich(event, options.sendIp !== false);
+        recorder?.errored();
+    });
     setClient(client);
     if (installed)
         return client;
@@ -41,7 +47,11 @@ export function init(options) {
         });
     });
     window.addEventListener("unhandledrejection", (e) => client.captureException(e.reason, { mechanism: { handler: "onunhandledrejection", handled: false } }));
-    addEventListener("pagehide", () => void client.flush(true));
+    const final = () => {
+        void client.flush(true);
+        recorder?.flush(true);
+    };
+    addEventListener("pagehide", final);
     const on = { fetch: true, xhr: true, navigation: true, click: true, console: true, ...options.breadcrumbs };
     const base = options.url.replace(/\/+$/, "");
     const crumb = (category, message, level, timestamp) => client.addBreadcrumb({ category, message, ...(level ? { level } : {}), ...(timestamp ? { timestamp } : {}) });
@@ -50,13 +60,14 @@ export function init(options) {
         if (on.navigation)
             crumb("navigation", hidden ? "Page hidden" : "Page visible");
         if (hidden)
-            void client.flush(true);
+            final();
     });
     const propagate = propagateTo(options.tracePropagationTargets ?? []);
-    if (on.fetch)
-        instrumentFetch(base, crumb, propagate);
-    if (on.xhr)
-        instrumentXhr(base, crumb, propagate);
+    const quiet = () => undefined;
+    if (on.fetch || recorder)
+        instrumentFetch(base, on.fetch ? crumb : quiet, propagate, recorder);
+    if (on.xhr || recorder)
+        instrumentXhr(base, on.xhr ? crumb : quiet, propagate, recorder);
     if (on.navigation)
         instrumentHistory(crumb);
     if (on.click)
@@ -122,7 +133,7 @@ function requestLine(method, url, status, start, span) {
     const ms = Math.round(performance.now() - start);
     return `${method.toUpperCase()} ${scrubUrl(url)} ${status} in ${ms}ms${span ? `, span ${span}` : ""}`;
 }
-function instrumentFetch(base, crumb, propagate) {
+function instrumentFetch(base, crumb, propagate, recorder) {
     const original = window.fetch;
     window.fetch = async function (input, init) {
         const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
@@ -137,18 +148,21 @@ function instrumentFetch(base, crumb, propagate) {
             init = { ...init, headers };
         }
         const start = performance.now();
+        const done = recorder?.request(method, url, span ?? randomHex(16));
         try {
             const res = await original.call(window, input, init);
             crumb("fetch", requestLine(method, url, res.status, start, span), res.status >= 400 ? "error" : undefined);
+            done?.(res.status);
             return res;
         }
         catch (e) {
             crumb("fetch", requestLine(method, url, "failed", start, span), "error");
+            done?.(0, e);
             throw e;
         }
     };
 }
-function instrumentXhr(base, crumb, propagate) {
+function instrumentXhr(base, crumb, propagate, recorder) {
     const proto = XMLHttpRequest.prototype;
     const open = proto.open;
     const send = proto.send;
@@ -171,7 +185,11 @@ function instrumentXhr(base, crumb, propagate) {
                 }
             }
             const start = performance.now();
-            this.addEventListener("loadend", () => crumb("fetch", requestLine(m[0], m[1], this.status || "failed", start, span), !this.status || this.status >= 400 ? "error" : undefined));
+            const done = recorder?.request(m[0], m[1], span ?? randomHex(16));
+            this.addEventListener("loadend", () => {
+                crumb("fetch", requestLine(m[0], m[1], this.status || "failed", start, span), !this.status || this.status >= 400 ? "error" : undefined);
+                done?.(this.status, this.status ? undefined : "The request failed: no response");
+            });
         }
         return send.call(this, body);
     };

package/dist/browser/spans.d.ts

@@ -0,0 +1,14 @@
+export interface Spans {
+    /** Starts a request span; call what it returns with the status or the error. */
+    request(method: string, url: string, spanId: string): (status: number, error?: unknown) => void;
+    /** The page has an event: send what it has, and keep sending. */
+    errored(): void;
+    flush(final: boolean): void;
+}
+export declare function spans(o: {
+    url: string;
+    key: string;
+    traceId: string;
+    fetch: typeof fetch;
+    beacon: (url: string, body: string) => boolean;
+}): Spans;

package/dist/browser/spans.js

@@ -0,0 +1,115 @@
+// The page's own requests as OpenTelemetry spans, so a trace shows what the browser did
+// around the server's spans. They wait in memory and are sent only once the page has
+// had an error: bertha keeps a trace only when an error names it.
+import { scrubUrl } from "../core/scrub.js";
+import { randomHex } from "../core/trace.js";
+import { endpoint } from "../core/transport.js";
+import { VERSION } from "../core/version.js";
+/** Spans a page holds before its first error, and sends in all. */
+const HELD = 200;
+const SENT = 1000;
+/** Time for the requests in flight when the error happened to finish. */
+const SETTLE_MS = 3000;
+export function spans(o) {
+    const target = `${endpoint(o.url, "traces")}?key=${encodeURIComponent(o.key)}`;
+    const origin = performance.timeOrigin || Date.now() - performance.now();
+    const now = () => origin + performance.now();
+    const page = { spanId: randomHex(16), parentSpanId: "", name: `page ${location.pathname}`, kind: 1, start: origin, end: origin, attributes: { "url.full": scrubUrl(location.href) } };
+    let held = [];
+    let sent = 0;
+    let loaded = false;
+    let armed = false;
+    let timer;
+    const later = () => (timer ??= setTimeout(() => flush(false), SETTLE_MS));
+    function flush(final) {
+        clearTimeout(timer);
+        timer = undefined;
+        if (!armed)
+            return;
+        const batch = held.splice(0, SENT - sent);
+        const nav = performance.getEntriesByType?.("navigation")[0];
+        const end = nav && (nav.loadEventEnd || nav.domContentLoadedEventEnd);
+        if (!loaded && nav && end) {
+            loaded = true;
+            batch.push({ spanId: randomHex(16), parentSpanId: page.spanId, name: "document load", kind: 1, start: origin + nav.startTime, end: origin + end, attributes: { "navigation.type": nav.type } });
+        }
+        if (!batch.length && !final)
+            return;
+        sent += batch.length;
+        // The page span grows with the page; bertha keeps its longest copy.
+        page.end = now();
+        batch.unshift(page);
+        const body = JSON.stringify(otlpJson(o.traceId, batch));
+        if (final && o.beacon(target, body))
+            return;
+        o.fetch(target, { method: "POST", headers: { "content-type": "text/plain" }, body, keepalive: body.length < 60_000, credentials: "omit" }).catch(() => undefined);
+    }
+    return {
+        request(method, url, spanId) {
+            const start = now();
+            let abs;
+            try {
+                abs = new URL(url, location.href);
+            }
+            catch {
+                // Recorded as the app wrote it.
+            }
+            const where = !abs ? url : abs.origin === location.origin ? abs.pathname : abs.host + abs.pathname;
+            return (status, error) => {
+                if (sent + held.length >= SENT)
+                    return;
+                const span = {
+                    spanId,
+                    parentSpanId: page.spanId,
+                    name: `${method.toUpperCase()} ${where}`,
+                    kind: 3,
+                    start,
+                    end: now(),
+                    attributes: { "http.request.method": method.toUpperCase(), "url.full": scrubUrl(abs?.href ?? url), ...(status ? { "http.response.status_code": status } : {}) },
+                    error: error !== undefined ? (error instanceof Error ? error.message : String(error)) : status >= 400 ? `HTTP ${status}` : undefined,
+                };
+                held.push(span);
+                if (!armed && held.length > HELD)
+                    held = held.slice(-HELD);
+                if (armed)
+                    later();
+            };
+        },
+        errored() {
+            armed = true;
+            later();
+        },
+        flush,
+    };
+}
+/** Epoch milliseconds as OTLP's nanoseconds, in a string: they're past 2^53. */
+function nanos(ms) {
+    return `${Math.round(ms * 1000)}000`;
+}
+function otlpJson(traceId, batch) {
+    // bertha keeps every attribute as text.
+    const attr = (key, v) => ({ key, value: { stringValue: String(v) } });
+    return {
+        resourceSpans: [
+            {
+                resource: { attributes: [attr("telemetry.sdk.language", "webjs"), attr("telemetry.sdk.name", "@bigbertha/sdk"), attr("telemetry.sdk.version", VERSION)] },
+                scopeSpans: [
+                    {
+                        scope: { name: "@bigbertha/sdk", version: VERSION },
+                        spans: batch.map((s) => ({
+                            traceId,
+                            spanId: s.spanId,
+                            parentSpanId: s.parentSpanId,
+                            name: s.name,
+                            kind: s.kind,
+                            startTimeUnixNano: nanos(s.start),
+                            endTimeUnixNano: nanos(s.end),
+                            attributes: Object.entries(s.attributes).map(([k, v]) => attr(k, v)),
+                            status: s.error ? { code: 2, message: s.error } : {},
+                        })),
+                    },
+                ],
+            },
+        ],
+    };
+}

package/dist/core/client.js

@@ -1,6 +1,7 @@
 // One client per app: builds events, scrubs them, batches them and sends them,
 // backing off when bertha asks it to.
 import { builtRelease, debugIdsFor } from "./debug-ids.js";
+import { activeSpan } from "./otel.js";
 import { scrubText, scrubUrl } from "./scrub.js";
 import { parseStack } from "./stack.js";
 import { versions } from "./versions.js";
@@ -118,7 +119,7 @@ export class Client {
             tags: { ...this.tags, ...ctx.tags },
             fingerprint: ctx.fingerprint,
             request: request && ctx.status !== undefined ? { ...request, status: ctx.status } : request,
-            trace: ctx.trace ?? fromReq.trace,
+            trace: ctx.trace ?? activeSpan() ?? fromReq.trace,
         };
         try {
             this.enrich?.(event);

package/dist/core/otel.d.ts

@@ -0,0 +1,3 @@
+import type { IngestTrace } from "./types.ts";
+/** The span the code is running in, so an error lands on it in the trace. */
+export declare function activeSpan(): IngestTrace | undefined;

package/dist/core/otel.js

@@ -0,0 +1,18 @@
+// The active OpenTelemetry span, when the app runs OpenTelemetry, read off the API's
+// global so the SDK doesn't depend on @opentelemetry/api.
+const API = Symbol.for("opentelemetry.js.api.1");
+const SPAN = Symbol.for("OpenTelemetry Context Key SPAN");
+const INVALID = /^0*$/;
+/** The span the code is running in, so an error lands on it in the trace. */
+export function activeSpan() {
+    try {
+        const api = globalThis[API];
+        const c = api?.context?.active?.().getValue?.(SPAN)?.spanContext?.();
+        if (!c?.traceId || !c.spanId || INVALID.test(c.traceId) || INVALID.test(c.spanId))
+            return undefined;
+        return { traceId: c.traceId, spanId: c.spanId };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/otlp.d.ts

@@ -0,0 +1,13 @@
+export interface OtlpOptions {
+    url?: string;
+    key?: string;
+}
+/**
+ * Settings for an OTLP/HTTP trace exporter (protobuf or JSON) that sends to bertha:
+ *   new OTLPTraceExporter(otlp())
+ * Reads BERTHA_URL and BERTHA_KEY unless given.
+ */
+export declare function otlp(options?: OtlpOptions): {
+    url?: string;
+    headers?: Record<string, string>;
+};

package/dist/core/otlp.js

@@ -0,0 +1,17 @@
+// Where an OpenTelemetry exporter sends spans to bertha.
+import { firstEnv } from "./env.js";
+import { endpoint } from "./transport.js";
+/**
+ * Settings for an OTLP/HTTP trace exporter (protobuf or JSON) that sends to bertha:
+ *   new OTLPTraceExporter(otlp())
+ * Reads BERTHA_URL and BERTHA_KEY unless given.
+ */
+export function otlp(options = {}) {
+    const key = options.key ?? firstEnv("BERTHA_KEY", "NEXT_PUBLIC_BERTHA_KEY");
+    const url = options.url ?? firstEnv("BERTHA_URL", "NEXT_PUBLIC_BERTHA_URL");
+    if (!key || !url) {
+        console.warn("[bertha] Set BERTHA_KEY and BERTHA_URL (or pass key and url). No spans will reach bertha.");
+        return {};
+    }
+    return { url: endpoint(url, "traces"), headers: { authorization: `Bearer ${key}` } };
+}

package/dist/core/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.6.1";
+export declare const VERSION = "0.8.0";

package/dist/core/version.js

@@ -1 +1 @@
-export const VERSION = "0.6.1";
+export const VERSION = "0.8.0";

package/dist/edge/index.d.ts

@@ -1,5 +1,7 @@
 import { Client } from "../core/client.ts";
 import type { Options } from "../core/types.ts";
 export { addBreadcrumb, captureException, captureMessage, flush, getClient, setTag, setUser } from "../core/hub.ts";
+export { otlp } from "../core/otlp.ts";
+export type { OtlpOptions } from "../core/otlp.ts";
 export type { CaptureContext, IngestEvent, Options } from "../core/types.ts";
 export declare function init(options?: Partial<Options>): Client | undefined;

package/dist/edge/index.js

@@ -7,6 +7,7 @@ import { fromAnyRequest } from "../core/request.js";
 import { fetchTransport, streamGzip } from "../core/transport.js";
 import { VERSION } from "../core/version.js";
 export { addBreadcrumb, captureException, captureMessage, flush, getClient, setTag, setUser } from "../core/hub.js";
+export { otlp } from "../core/otlp.js";
 export function init(options = {}) {
     const key = options.key ?? firstEnv("BERTHA_KEY", "NEXT_PUBLIC_BERTHA_KEY");
     const url = options.url ?? firstEnv("BERTHA_URL", "NEXT_PUBLIC_BERTHA_URL");

package/dist/next/index.d.ts

@@ -1,3 +1,5 @@
+export { otlp } from "../core/otlp.ts";
+export type { OtlpOptions } from "../core/otlp.ts";
 export declare function register(): Promise<void>;
 interface NextRequestInfo {
     path: string;
@@ -13,4 +15,3 @@ interface NextErrorContext {
 }
 /** Next calls this for errors in server components, route handlers, actions and middleware. */
 export declare function onRequestError(error: unknown, request: NextRequestInfo, context: NextErrorContext): Promise<void>;
-export {};

package/dist/next/index.js

@@ -2,6 +2,7 @@
 //   export { register, onRequestError } from "@bigbertha/sdk/next"
 import { captureException, flush } from "../core/hub.js";
 import { fromRequest } from "../core/request.js";
+export { otlp } from "../core/otlp.js";
 export async function register() {
     if (process.env.NEXT_RUNTIME === "nodejs")
         (await import("../node/index.js")).init();

package/dist/node/index.d.ts

@@ -1,6 +1,8 @@
 import { Client } from "../core/client.ts";
 import type { Options } from "../core/types.ts";
 export { addBreadcrumb, captureException, captureMessage, flush, getClient, setTag, setUser } from "../core/hub.ts";
+export { otlp } from "../core/otlp.ts";
+export type { OtlpOptions } from "../core/otlp.ts";
 export type { CaptureContext, IngestEvent, Options } from "../core/types.ts";
 export interface NodeOptions extends Partial<Options> {
     /** Report uncaught exceptions and unhandled rejections, then exit as Node would. On by default. */

package/dist/node/index.js

@@ -12,6 +12,7 @@ import { endpoint, fetchTransport } from "../core/transport.js";
 import { VERSION } from "../core/version.js";
 import { addContext } from "./context.js";
 export { addBreadcrumb, captureException, captureMessage, flush, getClient, setTag, setUser } from "../core/hub.js";
+export { otlp } from "../core/otlp.js";
 export const HEARTBEAT_MS = 20 * 60 * 1000;
 /** V8 keeps 10 frames, which a framework's own calls can use up before reaching yours. */
 export const STACK_FRAMES = 50;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigbertha/sdk",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Error reporting for bertha: browser, React, Node, edge and Next.js, with source maps by debug id.",
   "license": "MIT",
   "repository": {