@logbrew/sdk 0.1.32 → 0.1.34

package/README.md

@@ -367,7 +367,7 @@ If your app already owns an OpenTelemetry provider, `createLogBrewOpenTelemetryS
 
 ```js
 import { SpanKind } from "@opentelemetry/api";
-import { BasicTracerProvider } from "@opentelemetry/sdk-trace-base";
+import { TracerProvider } from "@opentelemetry/sdk-trace";
 import {
   createLogBrewOpenTelemetrySpanProcessor,
   LogBrewClient,
@@ -387,7 +387,7 @@ const processor = createLogBrewOpenTelemetrySpanProcessor({
   linkAttributeKeys: ["messaging.operation.name"],
   metadata: { release: "checkout@1.2.3", environment: "production" }
 });
-const provider = new BasicTracerProvider({ spanProcessors: [processor] });
+const provider = new TracerProvider({ spanProcessors: [processor] });
 const tracer = provider.getTracer("checkout-api");
 
 const span = tracer.startSpan("GET /orders/:id", {
@@ -407,7 +407,7 @@ await processor.forceFlush();
 If your OpenTelemetry setup already uses standard processors such as `SimpleSpanProcessor` or `BatchSpanProcessor`, use `createLogBrewOpenTelemetrySpanExporter()` instead:
 
 ```js
-import { BasicTracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { TracerProvider, SimpleSpanProcessor } from "@opentelemetry/sdk-trace";
 import {
   createLogBrewOpenTelemetrySpanExporter,
   LogBrewClient,
@@ -425,11 +425,13 @@ const exporter = createLogBrewOpenTelemetrySpanExporter({
   includeTraceSummary: true,
   metadata: { release: "checkout@1.2.3", environment: "production" }
 });
-const provider = new BasicTracerProvider({
-  spanProcessors: [new SimpleSpanProcessor(exporter)]
+const provider = new TracerProvider({
+  spanProcessors: [new SimpleSpanProcessor({ exporter })]
 });
 ```
 
+These examples use `@opentelemetry/sdk-trace` 3. With `@opentelemetry/sdk-trace-base` 2, use `BasicTracerProvider` and `new SimpleSpanProcessor(exporter)`; the LogBrew processor and exporter work the same with both.
+
 The OTel processor and exporter follow normal OTel sampled-span behavior by default and summarize up to eight span events and eight links. Set `includeTraceSummary: true` when you also want one synthetic `opentelemetry.trace:<root-name>` span per trace on processor `forceFlush()`/`shutdown()` or exporter `export()`/`forceFlush()`/`shutdown()`; the summary carries the trace ID, span count, error count, root span ID/name/kind, duration, and safe service/environment/route metadata so a batch reads like one request or transaction. They copy only a small safe default set such as service, environment, route, method, status code, span kind, instrumentation scope, exception type, exception event count, escaped exception count, and dropped-count metadata. Exception counts scan the readable span's events, while emitted exception type lists stay bounded. Escaped exception events on unset-status spans mark the LogBrew span as `error`; explicit OTel `OK` status stays `ok`. Additional event/link/span/resource attributes require explicit allowlists, and high-risk keys such as full URLs, headers, query strings, payloads, cookies, private auth values, DB statements, exception messages, and stacks stay blocked. Concurrent flush calls use one active send and one coalesced trailing drain: later spans leave the queue before their caller completes, while a failed active send consumes no extra retry budget. These helpers do not add an OpenTelemetry dependency, patch clients, own tracer providers, serialize baggage or tracestate, copy raw propagation headers, or capture request/response bodies.
 
 LogBrew severity categories are `info`, `warning`, `error`, and `critical`. The JavaScript SDK accepts common runtime aliases such as `trace`, `debug`, `warn`, and `fatal` for compatibility, then serializes canonical values before queued events are sent. The shared mapping is documented in the [LogBrew severity contract](../../docs/severity-contract.md).
@@ -506,7 +508,7 @@ When either queue limit is full, LogBrew drops the incoming event and keeps earl
 
 A fatal crash report (an issue with `fatal` or `critical` level) is the exception. When it does not fit, LogBrew removes the oldest queued events that are not fatal until it fits, and counts each removed event as `evicted_for_fatal`. It never removes events in a batch that is being sent or retried, and it removes nothing if the fatal still cannot fit. So a full queue drops a fatal only when everything else in it is fatal or in a batch that is being sent; that fatal is counted as `queue_overflow` or `queue_bytes_overflow`. A fatal larger than one request body is still dropped as `event_too_large`. Drop callbacks are advisory and must not interrupt application logging. The default queue remains memory-only; automatic delivery reduces normal flush work, while the app still calls `shutdown()` at its owned graceful-lifecycle boundary.
 
-LogBrew sees these drops too. The next request body carries the per-reason counts since the last accepted report, such as `"client_report":{"dropped_events":{"queue_overflow":3}}`. The client clears exactly those counts after a `2xx` response for that request; drops recorded while it is in flight, and counts in a failed or retried request, wait for the next one. A report never sends a request of its own, is left out when nothing was dropped, lists at most 16 reasons, caps each count at 1,000,000,000, and fits inside `maxBatchBytes`. Counts live in memory only, so drops not yet reported are lost when the process restarts.
+LogBrew sees these drops too. The next request body carries the per-reason counts since the last accepted report, such as `"client_report":{"report_id":"5f0c6a1e9b2d4c7a8e3f1b6d0a9c2e4f","dropped_events":{"queue_overflow":3}}`. The counts keep one `report_id` until a `2xx` response acknowledges a request that carried them, and LogBrew counts every resend of one report ID once, even when the resend carries different events. Drops recorded while a request is in flight wait for the next report. A report never sends a request of its own, is left out when nothing was dropped, lists at most 16 reasons, caps each count at 1,000,000,000, and fits inside `maxBatchBytes`. Without an `eventStore`, counts live in memory and drops not yet reported are lost when the process restarts. A store that also provides synchronous `loadClientReport()` and `saveClientReport(state)` keeps them: the client saves at once for a new report or reason and at most once a second during a drop burst, and after a restart resends a pending report under its original `report_id`. The Node and React Native persistent queues and browser `persistOffline` do this for you.
 
 Server runtimes can supply an explicit synchronous `eventStore` when they need restart recovery. The core loads and revalidates compact records during client creation, persists each accepted event before adding it to memory, persists an accepted prefix before removing it from memory, and closes the store only after successful shutdown. `purgePendingEvents()` clears both layers only while no flush or shutdown is queued or active. Implementations must provide synchronous `load`, `append`, `acknowledge`, `purge`, and `close` methods; use the encrypted `persistentQueue` adapter in `@logbrew/node` instead of writing a filesystem adapter from scratch. A store can also provide a synchronous `remove(indexes)` that deletes the records at those ascending `load()` positions. Fatal eviction needs it: a full queue on a store without `remove` drops the fatal as before.
 

package/browser-breadcrumbs.cjs

@@ -49,6 +49,7 @@ function patchConsole(target, add) {
     return [];
   }
   return Object.entries(CONSOLE_LEVELS).flatMap(([method, level]) => replaceMethod(target, method, (original) => (
+    /** @this {Console} */
     function logBrewConsoleBreadcrumb(...args) {
       const message = boundedText(consoleTemplate(args), MAX_MESSAGE_LENGTH);
       if (message) {
@@ -60,7 +61,7 @@ function patchConsole(target, add) {
 }
 
 function patchFetch(browserWindow, add, ignored) {
-  return replaceMethod(browserWindow, "fetch", (original) => async function logBrewFetchBreadcrumb(input, init) {
+  return replaceMethod(browserWindow, "fetch", (original) => /** @this {*} */ async function logBrewFetchBreadcrumb(input, init) {
     const method = String(init?.method ?? input?.method ?? "GET").toUpperCase();
     const url = sanitizeUrl(typeof input === "string" || input instanceof URL ? input : input?.url, browserWindow);
     try {
@@ -85,11 +86,11 @@ function patchXhr(browserWindow, add, ignored) {
   }
   const state = new WeakMap();
   return [
-    ...replaceMethod(prototype, "open", (original) => function logBrewXhrOpen(method, url, ...rest) {
+    ...replaceMethod(prototype, "open", (original) => /** @this {XMLHttpRequest} */ function logBrewXhrOpen(method, url, ...rest) {
       state.set(this, { method: String(method ?? "GET").toUpperCase(), url: sanitizeUrl(url, browserWindow) });
       return original.call(this, method, url, ...rest);
     }),
-    ...replaceMethod(prototype, "send", (original) => function logBrewXhrSend(...args) {
+    ...replaceMethod(prototype, "send", (original) => /** @this {XMLHttpRequest} */ function logBrewXhrSend(...args) {
       const request = state.get(this);
       if (request && !ignored.has(request.url) && typeof this.addEventListener === "function") {
         this.addEventListener("loadend", () => {
@@ -115,6 +116,7 @@ function patchNavigation(browserWindow, add) {
     }
   };
   const restores = ["pushState", "replaceState"].flatMap((method) => replaceMethod(history, method, (original) => (
+    /** @this {History} */
     function logBrewNavigationBreadcrumb(...args) {
       const result = original.apply(this, args);
       record();

package/core.cjs

@@ -96,6 +96,11 @@ const MAX_CLIENT_REPORT_REASONS = 16;
 const MAX_CLIENT_REPORT_COUNT = 1_000_000_000;
 const DELIVERY_HEALTH_SCHEMA_VERSION = 1;
 const EVENT_QUEUE_FACTORY = Symbol.for("@logbrew/sdk.eventQueueFactory");
+// Runtimes without an event store (browser storage) persist unreported drop counts through this seam.
+const CLIENT_REPORT_STORE = Symbol.for("@logbrew/sdk.clientReportStore");
+const CLIENT_REPORT_SAVE_INTERVAL_MS = 1_000;
+const CLIENT_REPORT_ID_PATTERN = /^[A-Za-z0-9_-]{16,64}$/u;
+const CLIENT_REPORT_REASON_PATTERN = /^[a-z][a-z0-9_]{0,63}$/u;
 const CONTEXT_PROVIDER = Symbol.for("@logbrew/sdk.contextProvider");
 // Runtime packages supply request-scoped breadcrumbs through this seam; core merges them into issues.
 const BREADCRUMB_PROVIDER = Symbol.for("@logbrew/sdk.breadcrumbProvider");
@@ -228,6 +233,7 @@ class LogBrewClient {
     onEventDropped,
     eventStore,
     [EVENT_QUEUE_FACTORY]: eventQueueFactory,
+    [CLIENT_REPORT_STORE]: clientReportStore,
     transport,
     automaticDelivery = transport !== undefined,
     deliveryIntervalMs = DEFAULT_DELIVERY_INTERVAL_MS,
@@ -261,6 +267,9 @@ class LogBrewClient {
     if (eventStore !== undefined && eventQueueFactory !== undefined) {
       throw new SdkError("validation_error", "eventStore and event queue factory are mutually exclusive");
     }
+    if (clientReportStore !== undefined && !isClientReportStore(clientReportStore)) {
+      throw new SdkError("validation_error", "client report store must provide loadClientReport and saveClientReport");
+    }
     validateTransport(transport);
     if (typeof automaticDelivery !== "boolean") {
       throw new SdkError("validation_error", "automaticDelivery must be a boolean");
@@ -284,6 +293,7 @@ class LogBrewClient {
       deliveryQueueThreshold,
       eventStore,
       eventQueueFactory,
+      clientReportStore,
       eventFilter,
       maxBatchBytes,
       maxBatchEvents,
@@ -318,6 +328,7 @@ class LogBrewClient {
     breadcrumbProvider,
     eventStore,
     eventQueueFactory,
+    clientReportStore,
     transport,
     automaticDelivery,
     deliveryIntervalMs,
@@ -382,8 +393,14 @@ class LogBrewClient {
       queue_bytes_overflow: 0,
       queue_overflow: 0
     };
-    // In memory only: counts not yet acknowledged by a 2xx are lost on restart.
-    this.unreportedDropsByReason = {};
+    // A persistent store keeps counts not yet acknowledged by a 2xx across restarts.
+    this.clientReportStore = clientReportStore
+      ?? (isClientReportStore(resolvedEventStore) ? resolvedEventStore : undefined);
+    this.clientReportSavedAtMs = 0;
+    const restoredReport = loadClientReport(this.clientReportStore);
+    this.unreportedDropsByReason = restoredReport.unreported;
+    // Drop counts frozen under one report ID until a 2xx acknowledges a body that carried them.
+    this.pendingClientReport = restoredReport.pending;
     this.lastDropReason = "none";
     this.storage = resolvedEventStore ? "persistent" : "memory";
     this.hydratedEventCount = recovered.events.length;
@@ -618,6 +635,7 @@ class LogBrewClient {
       if (controlsAutomaticDelivery) {
         this.#recordAutomaticSuccess();
       }
+      this.#saveClientReport(true);
       if (this.eventStore) {
         try {
           requireSynchronousStoreResult("close", this.eventStore.close());
@@ -784,7 +802,9 @@ class LogBrewClient {
   #recordDroppedEvent(event, reason) {
     this.droppedEventCount = incrementBounded(this.droppedEventCount);
     this.droppedEventsByReason[reason] = incrementBounded(this.droppedEventsByReason[reason]);
+    const firstOfReason = this.unreportedDropsByReason[reason] === undefined;
     this.unreportedDropsByReason[reason] = Math.min(MAX_CLIENT_REPORT_COUNT, (this.unreportedDropsByReason[reason] ?? 0) + 1);
+    this.#saveClientReport(firstOfReason);
     this.lastDropReason = reason;
     this.lastDroppedAtUnixMs = nextBoundedTimestamp(this.lastDroppedAtUnixMs);
     if (!this.onEventDropped) {
@@ -949,9 +969,10 @@ class LogBrewClient {
       const batch = this.unacknowledgedBatch;
       const response = await this.#sendBatch(transport, batch.body);
       this.unacknowledgedBatch = undefined;
-      // Clear only what this body carried; drops recorded while it was in flight stay pending.
-      for (const [reason, count] of Object.entries(batch.droppedEvents ?? {})) {
-        this.unreportedDropsByReason[reason] -= count;
+      // Drops recorded while this body was in flight stay pending under a new report ID.
+      if (batch.carriesClientReport) {
+        this.pendingClientReport = undefined;
+        this.#saveClientReport(true);
       }
       this.#acknowledge(batch.eventsCount);
       this.acceptedBatchCount = incrementBounded(this.acceptedBatchCount);
@@ -979,11 +1000,8 @@ class LogBrewClient {
   }
 
   #nextBatch(maxEvents) {
-    const reported = Object.entries(this.unreportedDropsByReason).filter(([, count]) => count > 0);
-    const droppedEvents = reported.length > 0
-      ? Object.fromEntries(reported.slice(0, MAX_CLIENT_REPORT_REASONS))
-      : undefined;
-    const reportSuffix = droppedEvents && `],"client_report":${JSON.stringify({ dropped_events: droppedEvents })}}`;
+    const report = this.#pendingClientReport();
+    const reportSuffix = report && `],"client_report":${JSON.stringify(report)}}`;
     const reportedEvents = reportSuffix ? this.#batchEventCount(maxEvents, utf8ByteLength(reportSuffix)) : 0;
     const eventsCount = reportedEvents || this.#batchEventCount(maxEvents, this.batchSuffixBytes);
     if (eventsCount === 0) {
@@ -991,11 +1009,45 @@ class LogBrewClient {
     }
     return {
       body: `${this.batchPrefix}${this.serializedEvents.slice(0, eventsCount).join(",")}${reportedEvents ? reportSuffix : this.batchSuffix}`,
-      droppedEvents: reportedEvents ? droppedEvents : undefined,
+      carriesClientReport: reportedEvents > 0,
       eventsCount
     };
   }
 
+  // Freezes unreported drops under one stable ID, so every resend of them is counted once.
+  #pendingClientReport() {
+    if (this.pendingClientReport === undefined) {
+      const reported = Object.entries(this.unreportedDropsByReason).filter(([, count]) => count > 0);
+      if (reported.length === 0) {
+        return undefined;
+      }
+      const droppedEvents = Object.fromEntries(reported.slice(0, MAX_CLIENT_REPORT_REASONS));
+      for (const reason of Object.keys(droppedEvents)) {
+        delete this.unreportedDropsByReason[reason];
+      }
+      this.pendingClientReport = Object.freeze({ report_id: randomHex(16), dropped_events: droppedEvents });
+      this.#saveClientReport(true);
+    }
+    return this.pendingClientReport;
+  }
+
+  // Saves at once for a new report or reason, and at most once a second during a drop burst.
+  #saveClientReport(immediately) {
+    const now = Date.now();
+    if (!this.clientReportStore || (!immediately && now - this.clientReportSavedAtMs < CLIENT_REPORT_SAVE_INTERVAL_MS)) {
+      return;
+    }
+    this.clientReportSavedAtMs = now;
+    try {
+      requireSynchronousStoreResult("saveClientReport", this.clientReportStore.saveClientReport({
+        pending: this.pendingClientReport ?? null,
+        unreported: { ...this.unreportedDropsByReason }
+      }));
+    } catch {
+      // Drop counts are advisory: a failed save keeps them in memory and never blocks capture.
+    }
+  }
+
   #batchEventCount(maxEvents, suffixBytes) {
     let bodyBytes = this.batchPrefixBytes + suffixBytes;
     let eventsCount = 0;
@@ -1193,6 +1245,50 @@ function isFatalEvent(event) {
   return event.type === "issue" && event.attributes.level === "critical";
 }
 
+// Report IDs only need uniqueness, so runtimes without Web Crypto fall back to Math.random.
+function randomHex(byteLength) {
+  const bytes = new Uint8Array(byteLength);
+  if (typeof globalThis.crypto?.getRandomValues === "function") {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let index = 0; index < bytes.length; index += 1) {
+      bytes[index] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function isClientReportStore(store) {
+  return typeof store?.loadClientReport === "function" && typeof store.saveClientReport === "function";
+}
+
+// Restores saved drop counts; anything unreadable or out of bounds is ignored, never fatal.
+function loadClientReport(store) {
+  let state;
+  try {
+    state = store ? requireSynchronousStoreResult("loadClientReport", store.loadClientReport()) : undefined;
+  } catch {
+    state = undefined;
+  }
+  const pending = state?.pending;
+  const pendingCounts = validClientReportCounts(pending?.dropped_events);
+  return {
+    pending: CLIENT_REPORT_ID_PATTERN.test(pending?.report_id ?? "") && Object.keys(pendingCounts).length > 0
+      ? Object.freeze({ report_id: pending.report_id, dropped_events: pendingCounts })
+      : undefined,
+    unreported: validClientReportCounts(state?.unreported)
+  };
+}
+
+function validClientReportCounts(counts) {
+  if (!counts || typeof counts !== "object" || Array.isArray(counts)) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(counts).filter(([reason, count]) => (
+    CLIENT_REPORT_REASON_PATTERN.test(reason) && Number.isSafeInteger(count) && count >= 1 && count <= MAX_CLIENT_REPORT_COUNT
+  )).slice(0, MAX_CLIENT_REPORT_REASONS));
+}
+
 function incrementBounded(value) {
   return value >= Number.MAX_SAFE_INTEGER ? Number.MAX_SAFE_INTEGER : value + 1;
 }
@@ -1226,7 +1322,7 @@ function createEventStoreFromQueueFactory(eventQueueFactory, config) {
     restoreEvent: restoreStoredEvent
   });
   validateEventQueue(queue);
-  return {
+  const eventStore = {
     load() {
       const events = queue.events();
       const count = queue.length();
@@ -1256,6 +1352,14 @@ function createEventStoreFromQueueFactory(eventQueueFactory, config) {
       return queue.close();
     }
   };
+  if (typeof queue.remove === "function") {
+    eventStore.remove = (indexes) => queue.remove(indexes);
+  }
+  if (isClientReportStore(queue)) {
+    eventStore.loadClientReport = () => queue.loadClientReport();
+    eventStore.saveClientReport = (state) => queue.saveClientReport(state);
+  }
+  return eventStore;
 }
 
 function validateEventQueue(queue) {
@@ -1491,6 +1595,7 @@ function installLogBrewConsoleCapture(config) {
 }
 
 function createConsoleCaptureMethod(config) {
+  /** @this {*} */
   return function logBrewConsoleMethod(...args) {
     config.original.apply(this, args);
     if (!config.state.installed) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/sdk",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "description": "Public LogBrew JavaScript SDK for building, validating, and flushing event batches.",
   "type": "module",
   "main": "./index.cjs",