@steve31415/baselib 1.0.0 → 2.1.0

package/dist/http.js

@@ -57,12 +57,15 @@ export function startServer(opts) {
     });
     process.once('SIGTERM', () => {
         opts.logger.info('SIGTERM received, shutting down');
+        // final: last-chance delivery + drop markers, time-boxed. The two racing
+        // callers below join the same single-flight finalFlush, so whichever
+        // fires second waits for the real work instead of exiting under it.
         server.close(() => {
-            void flushAllLoggers().finally(() => process.exit(0));
+            void flushAllLoggers({ final: true }).finally(() => process.exit(0));
         });
         // Cloud Run's grace period is 10s; don't rely on every socket closing.
         setTimeout(() => {
-            void flushAllLoggers().finally(() => process.exit(0));
+            void flushAllLoggers({ final: true }).finally(() => process.exit(0));
         }, 5000).unref();
     });
     return server;

package/dist/log-browser.js

@@ -6,6 +6,7 @@
 //   <meta name="pw-log-app" content="auth">
 //   <meta name="pw-log-dataset" content="apps">
 //   <meta name="pw-log-token" content="...ingest-only, dataset-scoped...">
+//   <meta name="pw-build-id" content="...deployment identity...">
 //
 // The token is ingest-only and dataset-scoped by design — visible to any
 // signed-in user, able to do nothing but add log events.
@@ -19,13 +20,21 @@ export function createBrowserLogger(opts = {}) {
     const dataset = opts.dataset ?? metaContent('pw-log-dataset') ?? 'apps';
     const token = opts.token ?? metaContent('pw-log-token');
     const baseUrl = opts.baseUrl ?? 'https://api.axiom.co';
+    const buildId = metaContent('pw-build-id');
     const shipper = token
         ? new LogShipper({
             url: `${baseUrl}/v1/datasets/${dataset}/ingest`,
             token,
+            // Chromium rejects keepalive request bodies over 64 KiB outright, so
+            // keep batches small; keepalive lets a flush started during page
+            // unload complete. Retries run while the page lives; page-death
+            // remains best-effort, so a browser give-up is only console-noted.
             batchSize: 20,
-            // keepalive lets a flush started during page unload complete.
             fetchInit: { keepalive: true },
+            onGiveUp: (batch, error, reason) => console.warn(`log ship dropped a batch (${reason}): ${String(error)}`, {
+                batch_id: batch.id,
+                events: batch.events.length,
+            }),
         })
         : undefined;
     function build(context) {
@@ -48,7 +57,7 @@ export function createBrowserLogger(opts = {}) {
             flush: () => shipper?.flush() ?? Promise.resolve(),
         };
     }
-    const logger = build(opts.context);
+    const logger = build({ ...(buildId ? { build_id: buildId } : {}), ...opts.context });
     // Ship what's pending whenever the page may be going away.
     const flushNow = () => void logger.flush();
     addEventListener('pagehide', flushNow);

package/dist/log-core.d.ts

@@ -28,29 +28,85 @@ export interface SerializedError {
 }
 export declare function serializeError(err: unknown): SerializedError;
 export declare function truncate(s: string, max: number): string;
+export type ShipFailureReason = 'give-up' | 'buffer-overflow' | 'shutdown';
+/** What failure callbacks see of a batch. `attempt` is attempts made so far. */
+export interface ShippedBatch {
+    id: string;
+    events: LogEvent[];
+    bytes: number;
+    firstTime: string;
+    lastTime: string;
+    attempt: number;
+    maxAttempts: number;
+}
 export interface ShipperOptions {
     /** Full ingest URL, e.g. https://api.axiom.co/v1/datasets/apps/ingest */
     url: string;
     token: string;
     batchSize?: number;
     intervalMs?: number;
+    /** Total delivery attempts per batch (default 4). */
+    maxAttempts?: number;
+    /** Backoff before attempt 2, 3, … (default [5s, 15s, 40s]). On an idle
+     *  Cloud Run instance the CPU is throttled between requests, so these
+     *  fire at the next CPU window (next request or shutdown), not on the
+     *  wall clock. */
+    retryDelaysMs?: number[];
+    /** Per-attempt fetch timeout (default 3s). */
+    attemptTimeoutMs?: number;
+    /** Caps across ALL undelivered batches; overflow drops oldest with an
+     *  onGiveUp('buffer-overflow'). Defaults 5000 events / 5 MB. */
+    maxBufferedEvents?: number;
+    maxBufferedBytes?: number;
     fetchFn?: typeof fetch;
     /** Extra fetch options (browser sets keepalive). */
     fetchInit?: RequestInit;
-    /** Called with the events that could not be delivered. */
-    onShipFailure?: (events: LogEvent[], error: unknown) => void;
+    /** A delivery attempt failed; the batch will be retried. */
+    onAttemptFailure?: (batch: ShippedBatch, error: unknown) => void;
+    /** The batch is abandoned — its events will never reach Axiom. */
+    onGiveUp?: (batch: ShippedBatch, error: unknown, reason: ShipFailureReason) => void;
 }
 export declare class LogShipper {
     private readonly opts;
     private queue;
-    private timer;
-    private inflight;
+    private pending;
+    private totalEvents;
+    private totalBytes;
+    private batchTimer;
+    private pumpTimer;
+    private pumping;
+    private closed;
+    private finalPromise;
+    private readonly inflight;
     private readonly batchSize;
     private readonly intervalMs;
+    private readonly maxAttempts;
+    private readonly retryDelaysMs;
+    private readonly attemptTimeoutMs;
+    private readonly maxBufferedEvents;
+    private readonly maxBufferedBytes;
     constructor(opts: ShipperOptions);
     enqueue(event: LogEvent): void;
+    /** Form a batch from the queue and give it (and any mature retries) an
+     *  attempt. Resolves once this call's batch has its first attempt settled
+     *  — raced with one attempt timeout, so it is bounded even when the pump
+     *  is busy with older batches. */
     flush(): Promise<void>;
+    /** Shutdown path: one parallel last-chance attempt for everything
+     *  undelivered, then a sweep that marks the rest dropped. Single-flight
+     *  while in flight (racing SIGTERM callers join one promise), but re-arms
+     *  after settling — a mid-run caller that logs afterward must not find a
+     *  stale settled promise that no-ops its real shutdown later. */
+    finalFlush(deadlineMs?: number): Promise<void>;
+    private formBatch;
+    private remove;
+    private giveUp;
+    private pump;
+    private schedulePump;
+    private attempt;
+    /** Returns the failure, or undefined on success. Never throws. */
     private ship;
+    private runFinal;
 }
 export interface EventFactoryOptions {
     app: string;

package/dist/log-core.js

@@ -2,7 +2,12 @@
 // serialization. Used by both the server logger (log.ts) and the browser
 // logger (log-browser.ts). Ships to Axiom's native JSON ingest — chosen over
 // OTLP for its synchronous commit and clean top-level field names (design:
-// ~/migration/research/base-services-design.md §4).
+// ~/migration/research/base-services-design.md §4). Delivery is hardened with
+// bounded, backed-off retries and per-batch identity
+// (~/migration/research/logging-reliability-design.md): every undelivered
+// batch either lands in Axiom or ends in an onGiveUp callback — the server
+// logger turns those into stdout drop markers that watchdog2's daily
+// ship-failure check counts.
 export function serializeError(err) {
     if (err instanceof Error) {
         const out = { name: err.name, message: err.message, stack: err.stack };
@@ -19,45 +24,224 @@ export function serializeError(err) {
 export function truncate(s, max) {
     return s.length <= max ? s : s.slice(0, max) + `…[+${s.length - max}]`;
 }
-// Batches events and ships them with plain fetch. Never throws from
-// enqueue(); delivery failures go to onShipFailure (the server logger falls
-// back to stdout, which Cloud Logging captures).
+function randomId() {
+    const c = globalThis.crypto;
+    return c?.randomUUID?.() ?? Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+function unrefTimer(t) {
+    ;
+    t.unref?.();
+}
+/** Resolve when `p` does, or after `ms` (unref'd — never holds the process). */
+function raceTimeout(p, ms) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        unrefTimer(t);
+        void p.then(() => { clearTimeout(t); resolve(); }, () => { clearTimeout(t); resolve(); });
+    });
+}
+// Batches events and ships them with plain fetch. enqueue() never throws.
+// One capped `pending` store holds every undelivered batch; a single serial
+// pump attempts one at a time; finalFlush() is the time-boxed, single-flight
+// shutdown path (parallel last-chance attempts, then a sweep that marks
+// everything undelivered as dropped).
 export class LogShipper {
     opts;
     queue = [];
-    timer;
-    inflight = Promise.resolve();
+    pending = [];
+    totalEvents = 0;
+    totalBytes = 0;
+    batchTimer;
+    pumpTimer;
+    pumping = false;
+    closed = false;
+    finalPromise;
+    inflight = new Set();
     batchSize;
     intervalMs;
+    maxAttempts;
+    retryDelaysMs;
+    attemptTimeoutMs;
+    maxBufferedEvents;
+    maxBufferedBytes;
     constructor(opts) {
         this.opts = opts;
         this.batchSize = opts.batchSize ?? 50;
         this.intervalMs = opts.intervalMs ?? 2000;
+        this.maxAttempts = opts.maxAttempts ?? 4;
+        this.retryDelaysMs = opts.retryDelaysMs ?? [5_000, 15_000, 40_000];
+        this.attemptTimeoutMs = opts.attemptTimeoutMs ?? 3_000;
+        this.maxBufferedEvents = opts.maxBufferedEvents ?? 5_000;
+        this.maxBufferedBytes = opts.maxBufferedBytes ?? 5 * 1024 * 1024;
     }
     enqueue(event) {
         this.queue.push(event);
         if (this.queue.length >= this.batchSize) {
             void this.flush();
         }
-        else if (!this.timer) {
-            this.timer = setTimeout(() => void this.flush(), this.intervalMs);
-            this.timer.unref?.();
+        else if (!this.batchTimer) {
+            this.batchTimer = setTimeout(() => void this.flush(), this.intervalMs);
+            // In Node, don't hold the process open just to flush logs.
+            unrefTimer(this.batchTimer);
         }
     }
+    /** Form a batch from the queue and give it (and any mature retries) an
+     *  attempt. Resolves once this call's batch has its first attempt settled
+     *  — raced with one attempt timeout, so it is bounded even when the pump
+     *  is busy with older batches. */
     flush() {
-        if (this.timer) {
-            clearTimeout(this.timer);
-            this.timer = undefined;
+        if (this.batchTimer) {
+            clearTimeout(this.batchTimer);
+            this.batchTimer = undefined;
         }
+        const batch = this.formBatch();
+        void this.pump();
+        const cap = this.attemptTimeoutMs + 500;
+        if (batch)
+            return raceTimeout(batch.firstAttempt, cap);
+        if (this.inflight.size > 0)
+            return raceTimeout(Promise.allSettled([...this.inflight]), cap);
+        return Promise.resolve();
+    }
+    /** Shutdown path: one parallel last-chance attempt for everything
+     *  undelivered, then a sweep that marks the rest dropped. Single-flight
+     *  while in flight (racing SIGTERM callers join one promise), but re-arms
+     *  after settling — a mid-run caller that logs afterward must not find a
+     *  stale settled promise that no-ops its real shutdown later. */
+    finalFlush(deadlineMs = 3_000) {
+        this.finalPromise ??= this.runFinal(deadlineMs).finally(() => {
+            this.finalPromise = undefined;
+            this.closed = false;
+        });
+        return this.finalPromise;
+    }
+    formBatch() {
         if (this.queue.length === 0)
-            return this.inflight;
-        const batch = this.queue;
+            return undefined;
+        const events = this.queue;
         this.queue = [];
-        // Chain so batches can't reorder or race; errors never propagate.
-        this.inflight = this.inflight.then(() => this.ship(batch));
-        return this.inflight;
+        const id = randomId();
+        events.forEach((e, i) => {
+            e.batch_id = id;
+            e.batch_seq = i;
+        });
+        const body = JSON.stringify(events);
+        let settleFirst;
+        const firstAttempt = new Promise((r) => (settleFirst = r));
+        const batch = {
+            id,
+            events,
+            body,
+            bytes: new TextEncoder().encode(body).length,
+            firstTime: events.reduce((m, e) => (e._time < m ? e._time : m), events[0]._time),
+            lastTime: events.reduce((m, e) => (e._time > m ? e._time : m), events[0]._time),
+            attempt: 0,
+            maxAttempts: this.maxAttempts,
+            nextAttemptAt: 0,
+            attempting: false,
+            terminal: false,
+            firstAttempt,
+            settleFirst,
+        };
+        // Enforce the caps over everything undelivered: evict oldest first; if
+        // nothing evictable remains, the new batch itself is the casualty.
+        while (this.totalEvents + events.length > this.maxBufferedEvents ||
+            this.totalBytes + batch.bytes > this.maxBufferedBytes) {
+            const victim = this.pending.find((b) => !b.attempting && !b.terminal);
+            if (!victim) {
+                batch.terminal = true;
+                settleFirst();
+                this.opts.onGiveUp?.(batch, new Error('retry buffer overflow'), 'buffer-overflow');
+                return undefined;
+            }
+            this.giveUp(victim, new Error('retry buffer overflow'), 'buffer-overflow');
+        }
+        this.pending.push(batch);
+        this.totalEvents += events.length;
+        this.totalBytes += batch.bytes;
+        return batch;
+    }
+    remove(batch) {
+        batch.terminal = true;
+        batch.settleFirst();
+        const i = this.pending.indexOf(batch);
+        if (i >= 0) {
+            this.pending.splice(i, 1);
+            this.totalEvents -= batch.events.length;
+            this.totalBytes -= batch.bytes;
+        }
+    }
+    giveUp(batch, error, reason) {
+        if (batch.terminal)
+            return;
+        this.remove(batch);
+        this.opts.onGiveUp?.(batch, error, reason);
+    }
+    // Serial drainer: one attempt in flight at a time. Reentrant-safe (the
+    // running loop picks up batches formed while it was awaiting).
+    async pump() {
+        if (this.pumping || this.closed)
+            return;
+        this.pumping = true;
+        try {
+            for (;;) {
+                const now = Date.now();
+                const batch = this.pending.find((b) => !b.attempting && !b.terminal && b.nextAttemptAt <= now);
+                if (!batch || this.closed)
+                    break;
+                await this.attempt(batch, this.attemptTimeoutMs);
+            }
+        }
+        finally {
+            this.pumping = false;
+            this.schedulePump();
+        }
+    }
+    schedulePump() {
+        if (this.pumpTimer) {
+            clearTimeout(this.pumpTimer);
+            this.pumpTimer = undefined;
+        }
+        if (this.closed)
+            return;
+        const times = this.pending.filter((b) => !b.attempting && !b.terminal).map((b) => b.nextAttemptAt);
+        if (times.length === 0)
+            return;
+        const delay = Math.max(0, Math.min(...times) - Date.now());
+        this.pumpTimer = setTimeout(() => void this.pump(), delay);
+        unrefTimer(this.pumpTimer);
     }
-    async ship(batch) {
+    // One delivery attempt. All state transitions are synchronous around the
+    // single await; a batch marked terminal meanwhile (shutdown sweep) is left
+    // alone — never double-marked, never re-buffered.
+    attempt(batch, timeoutMs) {
+        batch.attempting = true;
+        const p = (async () => {
+            const error = await this.ship(batch.body, timeoutMs);
+            batch.attempting = false;
+            if (batch.terminal)
+                return;
+            batch.attempt++;
+            batch.settleFirst();
+            if (error === undefined) {
+                this.remove(batch);
+            }
+            else if (batch.attempt >= this.maxAttempts) {
+                this.giveUp(batch, error, 'give-up');
+            }
+            else {
+                this.opts.onAttemptFailure?.(batch, error);
+                batch.nextAttemptAt =
+                    Date.now() + this.retryDelaysMs[Math.min(batch.attempt - 1, this.retryDelaysMs.length - 1)];
+                this.schedulePump();
+            }
+        })();
+        this.inflight.add(p);
+        void p.finally(() => this.inflight.delete(p));
+        return p;
+    }
+    /** Returns the failure, or undefined on success. Never throws. */
+    async ship(body, timeoutMs) {
         const fetchFn = this.opts.fetchFn ?? fetch;
         try {
             const res = await fetchFn(this.opts.url, {
@@ -67,14 +251,65 @@ export class LogShipper {
                     authorization: `Bearer ${this.opts.token}`,
                     'content-type': 'application/json',
                 },
-                body: JSON.stringify(batch),
+                body,
+                signal: AbortSignal.timeout(timeoutMs),
             });
-            if (!res.ok) {
-                this.opts.onShipFailure?.(batch, new Error(`ingest returned ${res.status}`));
-            }
+            return res.ok ? undefined : new Error(`ingest returned ${res.status}`);
         }
         catch (err) {
-            this.opts.onShipFailure?.(batch, err);
+            return err ?? new Error('ship failed');
+        }
+    }
+    async runFinal(deadlineMs) {
+        this.closed = true; // stops the pump loop and its timer
+        if (this.batchTimer)
+            clearTimeout(this.batchTimer);
+        if (this.pumpTimer)
+            clearTimeout(this.pumpTimer);
+        const deadline = Date.now() + deadlineMs;
+        const attempted = new Set();
+        // Last-chance attempts run in parallel (the serial-pump bound is
+        // deliberately waived at shutdown so late batches aren't starved), each
+        // at most once, time-boxed by the remaining deadline.
+        const attemptAll = () => {
+            this.formBatch();
+            for (const b of [...this.pending]) {
+                const remaining = deadline - Date.now();
+                if (remaining <= 0)
+                    break;
+                if (!b.attempting && !b.terminal && !attempted.has(b)) {
+                    attempted.add(b);
+                    void this.attempt(b, Math.min(this.attemptTimeoutMs, remaining));
+                }
+            }
+        };
+        // Await in-flight work against a REF'd deadline timer (an unref'd one
+        // would let a draining process exit before the sweep below writes the
+        // drop markers), re-running attemptAll after each wake so a batch whose
+        // pump attempt was in flight at entry — typically the newest — still
+        // gets its once-only last chance when that attempt fails early.
+        for (;;) {
+            attemptAll();
+            if (Date.now() >= deadline)
+                break;
+            const moreToStart = this.pending.some((b) => !b.attempting && !b.terminal && !attempted.has(b));
+            if (this.inflight.size === 0 && this.queue.length === 0 && !moreToStart)
+                break;
+            let timer;
+            const sleep = new Promise((r) => (timer = setTimeout(r, Math.max(1, deadline - Date.now()))));
+            await Promise.race([Promise.allSettled([...this.inflight]), sleep]);
+            clearTimeout(timer);
+        }
+        // Sweep: everything still undelivered — in flight or never attempted —
+        // is dropped with a marker. (An attempt still in flight may yet land:
+        // the rare phantom drop, accepted and documented for triage.) No awaits
+        // between here and resolution: settlement must reach the callers'
+        // exit handlers through microtasks alone, so nothing can be enqueued
+        // marker-less after the sweep. Note the cap inversion during this
+        // phase: with every batch attempting, overflow drops the NEWEST batch
+        // (nothing older is evictable) — bounded and marked, accepted.
+        for (const b of [...this.pending]) {
+            this.giveUp(b, new Error('undelivered at shutdown'), 'shutdown');
         }
     }
 }

package/dist/log.d.ts

@@ -1,6 +1,6 @@
-import { Logger } from './log-core.js';
+import { Logger, LogShipper, ShipperOptions } from './log-core.js';
 export { LogShipper, serializeError, truncate } from './log-core.js';
-export type { Logger, LogEvent, LogLevel, ShipperOptions } from './log-core.js';
+export type { Logger, LogEvent, LogLevel, ShipperOptions, ShippedBatch, ShipFailureReason, } from './log-core.js';
 export interface LoggerOptions {
     /** App name, e.g. 'auth'. Becomes the `app` field queried in Axiom. */
     app: string;
@@ -15,6 +15,21 @@ export interface LoggerOptions {
     context?: Record<string, unknown>;
     fetchFn?: typeof fetch;
 }
-/** Flush every logger created by createLogger (used at graceful shutdown). */
-export declare function flushAllLoggers(): Promise<void>;
+/** Register a directly-constructed shipper (e.g. watchdog2's platform-dataset
+ *  shipper) so flushAllLoggers and shutdown cover it too. */
+export declare function registerShipper(shipper: LogShipper): void;
+/** Flush every registered shipper. `final` is the shutdown path: time-boxed
+ *  last-chance delivery, then drop markers for whatever remains (see
+ *  LogShipper.finalFlush) — racing callers join the same underlying work. */
+export declare function flushAllLoggers(opts?: {
+    final?: boolean;
+}): Promise<void>;
+/** Ship-failure marker callbacks, writing one JSON line per event to stdout.
+ *  writeSync, not process.stdout.write: the markers must survive an
+ *  immediately following process.exit(), which can truncate async pipe
+ *  writes — they are the only record that a batch never reached Axiom.
+ *  first_time/last_time are the batch's own event-time range; the marker
+ *  line itself can be written minutes later (next CPU window), so triage
+ *  windows on these fields, never on the marker's timestamp. */
+export declare function stdoutShipMarkers(app: string, dataset: string): Pick<ShipperOptions, 'onAttemptFailure' | 'onGiveUp'>;
 export declare function createLogger(opts: LoggerOptions): Logger;

package/dist/log.js

@@ -6,12 +6,74 @@
 // a real problem; log entry points, outbound calls, and DB writes with ids;
 // rich meta is encouraged, but keep meta keys disciplined — every distinct
 // flattened key becomes an Axiom field (dataset cap 1024).
+import { writeSync } from 'node:fs';
 import { LogShipper, makeEvent, } from './log-core.js';
 export { LogShipper, serializeError, truncate } from './log-core.js';
-const allLoggers = new Set();
-/** Flush every logger created by createLogger (used at graceful shutdown). */
-export async function flushAllLoggers() {
-    await Promise.all([...allLoggers].map((l) => l.flush()));
+// Registry of every shipper created here (plus any registered explicitly),
+// used by flushAllLoggers and graceful shutdown. Shipper-level on purpose:
+// with() children share their root's shipper, so registering loggers leaked
+// one entry per child.
+const allShippers = new Set();
+/** Register a directly-constructed shipper (e.g. watchdog2's platform-dataset
+ *  shipper) so flushAllLoggers and shutdown cover it too. */
+export function registerShipper(shipper) {
+    allShippers.add(shipper);
+}
+/** Flush every registered shipper. `final` is the shutdown path: time-boxed
+ *  last-chance delivery, then drop markers for whatever remains (see
+ *  LogShipper.finalFlush) — racing callers join the same underlying work. */
+export async function flushAllLoggers(opts = {}) {
+    await Promise.all([...allShippers].map((s) => (opts.final ? s.finalFlush() : s.flush())));
+}
+/** Ship-failure marker callbacks, writing one JSON line per event to stdout.
+ *  writeSync, not process.stdout.write: the markers must survive an
+ *  immediately following process.exit(), which can truncate async pipe
+ *  writes — they are the only record that a batch never reached Axiom.
+ *  first_time/last_time are the batch's own event-time range; the marker
+ *  line itself can be written minutes later (next CPU window), so triage
+ *  windows on these fields, never on the marker's timestamp. */
+export function stdoutShipMarkers(app, dataset) {
+    const write = (line) => {
+        try {
+            writeSync(1, JSON.stringify(line) + '\n');
+        }
+        catch {
+            // stdout is gone; nothing further to do.
+        }
+    };
+    return {
+        onAttemptFailure: (batch, error) => write({
+            severity: 'WARNING',
+            app,
+            dataset,
+            kind: 'log-ship-failure',
+            batch_id: batch.id,
+            events: batch.events.length,
+            bytes: batch.bytes,
+            first_time: batch.firstTime,
+            last_time: batch.lastTime,
+            attempt: batch.attempt,
+            max_attempts: batch.maxAttempts,
+            error: String(error),
+            message: `axiom ship attempt ${batch.attempt}/${batch.maxAttempts} failed: ${String(error)} ` +
+                `(${batch.events.length} events, ${batch.bytes} bytes; will retry)`,
+        }),
+        onGiveUp: (batch, error, reason) => write({
+            severity: 'ERROR',
+            app,
+            dataset,
+            kind: 'log-ship-drop',
+            batch_id: batch.id,
+            events: batch.events.length,
+            bytes: batch.bytes,
+            first_time: batch.firstTime,
+            last_time: batch.lastTime,
+            reason,
+            error: String(error),
+            message: `axiom ship dropped a batch (${reason}): ${String(error)} ` +
+                `(${batch.events.length} events, ${batch.bytes} bytes; stdout mirror has them)`,
+        }),
+    };
 }
 export function createLogger(opts) {
     const token = opts.token ?? process.env.AXIOM_INGEST_TOKEN;
@@ -23,18 +85,15 @@ export function createLogger(opts) {
             url: `${baseUrl}/v1/datasets/${dataset}/ingest`,
             token,
             fetchFn: opts.fetchFn,
-            onShipFailure: (events, error) => {
-                // The stdout mirror already carried these events; record the
-                // delivery failure itself so Axiom gaps are explainable.
-                process.stdout.write(JSON.stringify({
-                    severity: 'WARNING',
-                    message: `axiom ship failed: ${String(error)} (${events.length} events; stdout mirror has them)`,
-                    app: opts.app,
-                    kind: 'log-ship-failure',
-                }) + '\n');
-            },
+            ...stdoutShipMarkers(opts.app, dataset),
         })
         : undefined;
+    if (shipper) {
+        registerShipper(shipper);
+        // Scripts/jobs: when the event loop drains, make the last-chance
+        // attempt and write drop markers for anything undelivered.
+        process.once('beforeExit', () => void shipper.finalFlush());
+    }
     function build(context) {
         const factory = { app: opts.app, source: 'server', context };
         const emit = (level, message, meta) => {
@@ -43,7 +102,7 @@ export function createLogger(opts) {
                 process.stdout.write(JSON.stringify(event) + '\n');
             shipper?.enqueue(event);
         };
-        const logger = {
+        return {
             debug: (m, meta) => emit('debug', m, meta),
             info: (m, meta) => emit('info', m, meta),
             warn: (m, meta) => emit('warn', m, meta),
@@ -51,11 +110,6 @@ export function createLogger(opts) {
             with: (extra) => build({ ...context, ...extra }),
             flush: () => shipper?.flush() ?? Promise.resolve(),
         };
-        allLoggers.add(logger);
-        return logger;
     }
-    const root = build(opts.context);
-    // Best-effort flush when the event loop drains (covers scripts/jobs).
-    process.once('beforeExit', () => void root.flush());
-    return root;
+    return build(opts.context);
 }

package/dist/rum.d.ts

@@ -3,5 +3,7 @@ export interface RumOptions {
     dataset?: string;
     token?: string;
     baseUrl?: string;
+    /** Defaults to the page's pw-build-id meta tag. */
+    buildId?: string;
 }
 export declare function initRum(opts?: RumOptions): void;

package/dist/rum.js

@@ -15,6 +15,7 @@ export function initRum(opts = {}) {
     const token = opts.token ?? metaContent('pw-log-token');
     if (!token)
         return;
+    const buildId = opts.buildId ?? metaContent('pw-build-id');
     const dataset = opts.dataset ?? 'rum';
     const baseUrl = (opts.baseUrl ?? 'https://api.axiom.co').replace(/\/$/, '');
     const shipper = new LogShipper({
@@ -40,6 +41,7 @@ export function initRum(opts = {}) {
             metric_id: m.id,
             navigation_type: m.navigationType,
             path: location.pathname,
+            ...(buildId ? { build_id: buildId } : {}),
         });
     };
     onLCP(report);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "1.0.0",
+  "version": "2.1.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, http",
   "type": "module",
   "license": "MIT",