@tallyrow/safesignal 1.0.1 → 1.3.0

package/README.md

@@ -43,8 +43,9 @@ log.info('checkout opened', { cartItems: 3 });
 
 - Ship an HTTP/beacon transport in the default entry — use the
   `./transport-beacon` subpath for the first-party body-only HTTPS
-  transport, or implement `Transport` yourself for a custom
-  delivery primitive.
+  transport, the `./transport-otlp` subpath to ship OTLP/HTTP+JSON
+  to any OTLP backend, or implement `Transport` yourself for a
+  custom delivery primitive.
 - Read `process.env.NODE_ENV`, `import.meta.env`, `location`, or
   `document.cookie` — pass `environment` explicitly.
 - Install global listeners or singletons (RUM-style automatic
@@ -104,6 +105,125 @@ The transport:
   `transport_shutdown_failed`. Wire the hook to **both** layers
   above for full coverage.
 
+## Ship logs to OTLP — `./transport-otlp` subpath
+
+To deliver SafeSignal's events to **any OTLP-compatible backend**
+(Datadog, Honeycomb, Grafana, an OpenTelemetry Collector,
+ClickHouse, …), import `createOtlpTransport` from the
+`./transport-otlp` subpath. It emits standard **OTLP/HTTP+JSON**
+logs — vendor-neutral, with zero new runtime dependencies and no
+`@opentelemetry/*` in the bundle.
+
+```ts
+import { configureLogging, getRootLogger } from '@tallyrow/safesignal';
+import { createOtlpTransport } from '@tallyrow/safesignal/transport-otlp';
+
+configureLogging({
+  application: { name: 'checkout-web', version: '4.2.0' },
+  environment: 'production',
+  transports: [
+    createOtlpTransport({
+      endpoint: 'https://otlp.example.com/v1/logs', // full OTLP logs URL, HTTPS
+      headers: { 'x-api-key': process.env.OTLP_API_KEY! }, // sent only on the wire
+      batching: { maxBatchSize: 20, maxBatchAgeMs: 5000 },
+    }),
+  ],
+});
+
+getRootLogger().info('checkout.started', { cartId: 'c_123', itemCount: 3 });
+```
+
+What it guarantees:
+
+- **OTLP/HTTP+JSON** `LogRecord`s with your application/module/
+  environment identity mapped to the OTLP `Resource`
+  (`service.name`, `service.version`, `deployment.environment`;
+  `module.*` per-record). Levels map to OTLP severity
+  (`debug`→5, `info`→9, `warn`→13, `error`→17).
+- **Fail-safe**: `fetch` with `keepalive` delivery, **no retry** —
+  a down/slow/erroring backend never throws into your code and
+  never breaks the page. Failed batches are dropped with one
+  rate-limited `onInternalError` notice per failure class
+  (`oversized_event`, `buffer_overflow`, `delivery_unavailable`,
+  `send_failed`, `partial_rejection`, `serialize_failed`,
+  `shutdown_failed`).
+- **Secure**: events are already redacted before the transport
+  sees them; auth headers are sent only on the request and never
+  appear in payloads, diagnostics, or the bundle. HTTPS-only
+  (loopback `http://` requires explicit `allowInsecureLoopback`).
+- **Lightweight & federated**: the transport is configured once at
+  the runtime level; the host owns it, federated modules do not
+  replace it, and duplicate package copies are **isolated**. Local
+  collectors: `endpoint: 'http://localhost:4318/v1/logs'` with
+  `allowInsecureLoopback: true`.
+
+## Correlate logs with traces — W3C trace context
+
+Supply a **W3C Trace Context** and SafeSignal carries `trace_id` / `span_id`
+on every event; when shipped via `./transport-otlp`, they populate the OTLP
+`LogRecord`'s standard `traceId` / `spanId` / `flags` fields, so any backend
+joins each log to its trace. SafeSignal is **carry-only** — it never mints ids.
+
+```ts
+import { configureLogging, getRootLogger, parseTraceparent } from '@tallyrow/safesignal';
+
+// From a header string the app already holds (e.g. SSR-injected):
+const trace = parseTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01');
+
+configureLogging({
+  application: { name: 'checkout-web' },
+  environment: 'production',
+  context: trace ? { trace } : {},
+  // …or dynamically, per emit, from your tracer's active span:
+  correlation: () => {
+    const s = myTracer.activeSpan();
+    return s ? { trace: { traceId: s.traceId, spanId: s.spanId, traceFlags: 1 } } : {};
+  },
+});
+
+getRootLogger().info('payment.authorized', { amount: 4200 });
+```
+
+- **Carry-only / fail-safe**: no supplied context ⇒ no trace fields; a malformed
+  `traceparent`, wrong-length/all-zero id, or oversized `tracestate` is dropped
+  fail-closed — the event still ships, no throw.
+- **Secure**: trace ids are identifiers, not secrets; `tracestate` is bounded;
+  existing redaction is unaffected.
+- **Vendor-neutral**: pure W3C — works with any tracer; the `./transport-otlp`
+  bundle stays `@opentelemetry`-free. Trace context layers through the same
+  context-merge precedence (root → logger chain → `correlation()`); host and
+  federated modules each contribute without per-`Logger` cost.
+
+### Tag the delivery request with `traceparent`
+
+Beyond the per-`LogRecord` trace fields above, the `./transport-otlp` transport
+can also set a W3C `traceparent` (and `tracestate`) **request header** on the
+delivery request itself, so a backend or collector can join the ingest request
+to its trace. It is **off by default** — opt in per transport:
+
+```ts
+const transport = createOtlpTransport({
+  endpoint: 'https://otlp.example.com/v1/logs',
+  headers: { authorization: `Bearer ${token}` }, // sent only on the wire
+  injectTraceparent: true, // ← opt in
+});
+```
+
+A delivery request carries the header **only when every event in the flushed
+batch shares one valid trace context** (the common case for a burst of logs in
+one span); a mixed-trace, trace-less, or empty batch sends no header — never an
+arbitrary "representative" one. `tracestate` rides along only when it is
+identical across the batch (and within the 512-char bound).
+
+- **Carry-only / fail-safe**: built from the events' existing `context.trace`;
+  no ids are minted, header construction never throws into a logging call or
+  blocks delivery, and the event payload is byte-identical either way.
+- **Secure**: the header carries only trace identifiers + bounded `tracestate`;
+  it never overwrites, duplicates, or exposes your auth/secret `headers`
+  (a consumer-supplied `traceparent` wins). Only `./transport-otlp` supports it
+  — `navigator.sendBeacon` cannot set custom request headers, so
+  `./transport-beacon` is out of scope.
+
 ## Level configuration
 
 In `production`, `debug` and `info` are dropped by default. Raise the
@@ -291,11 +411,11 @@ Reference docs and design history:
 
 The following are forward-looking items (not shipping today):
 
-- **Trace-context propagation** — W3C Trace Context (`traceparent`,
-  `tracestate`) for correlating frontend logs with backend traces.
-- **`./transport-otlp` subpath** — OTel-formatted events; ships to
-  any OTLP-compatible backend (Datadog, Honeycomb, Grafana
-  Tempo + Loki, self-hosted ClickHouse, etc.).
+- **OTLP/HTTP+protobuf encoding** for the
+  [`./transport-otlp`](#ship-logs-to-otlp--transport-otlp-subpath)
+  subpath — the subpath ships **JSON** today behind an internal
+  encoding seam; a protobuf encoder is an additive follow-up (no
+  public-API change).
 - **RUM features** — Web Vitals, automatic error capture, view
   tracking, network instrumentation (planned as opt-in subpaths
   under `./rum-*`).

package/dist/index.cjs

@@ -20,12 +20,16 @@ function mergeContexts(...sources) {
         src.attributes
       );
     }
+    if (src.trace !== void 0) {
+      merged.trace = src.trace;
+    }
   }
   const out = {};
   if (merged.application !== void 0) out.application = merged.application;
   if (merged.module !== void 0) out.module = merged.module;
   if (merged.environment !== void 0) out.environment = merged.environment;
   if (merged.attributes !== void 0) out.attributes = merged.attributes;
+  if (merged.trace !== void 0) out.trace = merged.trace;
   return out;
 }
 function deepMergeAttributes(earlier, later) {
@@ -94,7 +98,7 @@ function escapeControlChars(value) {
   if (!HAS_CONTROL_CHAR.test(value)) return value;
   return value.replace(CONTROL_CHAR_GLOBAL, (ch) => {
     const code = ch.charCodeAt(0);
-    return "\\u" + code.toString(16).padStart(4, "0");
+    return `\\u${code.toString(16).padStart(4, "0")}`;
   });
 }
 var controlCharGuard = (event, _config) => {
@@ -242,7 +246,10 @@ function createRedactor(rules) {
     let error = event.error;
     if (event.error !== void 0) {
       const escName = applyShapeRules(event.error.name, compiled.shapeRules);
-      const escMessage = applyShapeRules(event.error.message, compiled.shapeRules);
+      const escMessage = applyShapeRules(
+        event.error.message,
+        compiled.shapeRules
+      );
       const stack = event.error.stack;
       const escStack = stack === void 0 ? void 0 : applyShapeRules(stack, compiled.shapeRules);
       const errorChanged = escName !== event.error.name || escMessage !== event.error.message || escStack !== stack;
@@ -367,12 +374,13 @@ function isLogEventShape(value) {
     return false;
   }
   const obj = value;
-  if (typeof obj["timestamp"] !== "string") return false;
-  if (typeof obj["level"] !== "string") return false;
-  if (!VALID_LEVELS.has(obj["level"])) return false;
-  if (typeof obj["message"] !== "string") return false;
-  if (obj["attributes"] === null || typeof obj["attributes"] !== "object") return false;
-  if (obj["context"] === null || typeof obj["context"] !== "object") return false;
+  if (typeof obj.timestamp !== "string") return false;
+  if (typeof obj.level !== "string") return false;
+  if (!VALID_LEVELS.has(obj.level)) return false;
+  if (typeof obj.message !== "string") return false;
+  if (obj.attributes === null || typeof obj.attributes !== "object")
+    return false;
+  if (obj.context === null || typeof obj.context !== "object") return false;
   return true;
 }
 
@@ -452,7 +460,8 @@ function sanitizeValueImpl(value, depth, ctx) {
   if (depth > ctx.maxDepth) return "[MaxDepth]";
   if (value === null) return null;
   const t = typeof value;
-  if (t === "string") return truncateString(value, ctx.maxStringLength);
+  if (t === "string")
+    return truncateString(value, ctx.maxStringLength);
   if (t === "number") {
     const n = value;
     return Number.isFinite(n) ? n : null;
@@ -562,7 +571,7 @@ function sanitizeErrorAsAttribute(err, depth, ctx) {
   };
   const stack = safeOptional(() => err.stack);
   if (stack !== void 0) {
-    reduced["stack"] = stack;
+    reduced.stack = stack;
   }
   return sanitizeObject(reduced, depth, ctx);
 }
@@ -683,7 +692,7 @@ var urlScrub = (event, _config) => {
   const message = maybeScrubString(event.message);
   const attributes = walkAttributes2(event.attributes);
   const context = walkContext3(event.context);
-  let error = void 0;
+  let error;
   if (event.error !== void 0) {
     const scrubbedMessage = maybeScrubString(event.error.message);
     const stack = event.error.stack;
@@ -747,7 +756,7 @@ function scrubHashFragment(parsed, extras) {
     }
   }
   if (!changed) return false;
-  parsed.hash = "#" + out.join("&");
+  parsed.hash = `#${out.join("&")}`;
   return true;
 }
 function isDenied(name, extras) {
@@ -1110,6 +1119,36 @@ function installRuntime(runtime) {
   return previous;
 }
 
+// src/trace/validate.ts
+var MAX_TRACESTATE_LEN = 512;
+var TRACE_ID_RE = /^[0-9a-f]{32}$/;
+var SPAN_ID_RE = /^[0-9a-f]{16}$/;
+var ALL_ZERO_TRACE_ID = "0".repeat(32);
+var ALL_ZERO_SPAN_ID = "0".repeat(16);
+function isValidTraceId(value) {
+  return typeof value === "string" && TRACE_ID_RE.test(value) && value !== ALL_ZERO_TRACE_ID;
+}
+function isValidSpanId(value) {
+  return typeof value === "string" && SPAN_ID_RE.test(value) && value !== ALL_ZERO_SPAN_ID;
+}
+function normalizeTraceContext(candidate) {
+  if (typeof candidate !== "object" || candidate === null) {
+    return void 0;
+  }
+  const c = candidate;
+  if (!isValidTraceId(c.traceId) || !isValidSpanId(c.spanId)) {
+    return void 0;
+  }
+  const trace = { traceId: c.traceId, spanId: c.spanId };
+  if (typeof c.traceFlags === "number" && Number.isInteger(c.traceFlags) && c.traceFlags >= 0 && c.traceFlags <= 255) {
+    trace.traceFlags = c.traceFlags;
+  }
+  if (typeof c.traceState === "string" && c.traceState.length > 0 && c.traceState.length <= MAX_TRACESTATE_LEN) {
+    trace.traceState = c.traceState;
+  }
+  return trace;
+}
+
 // src/api/logger.ts
 var rootLogger;
 function installState(config) {
@@ -1182,6 +1221,14 @@ function makeLogger(options, chainedContexts) {
       ...chainedContexts,
       correlation
     );
+    if (context.trace !== void 0) {
+      const normalized = normalizeTraceContext(context.trace);
+      if (normalized === void 0) {
+        delete context.trace;
+      } else {
+        context.trace = normalized;
+      }
+    }
     const event = buildLogEvent({
       level,
       message,
@@ -1213,6 +1260,27 @@ function makeLogger(options, chainedContexts) {
   };
 }
 
+// src/trace/traceparent.ts
+var VERSION_RE = /^[0-9a-f]{2}$/;
+function parseTraceparent(traceparent, tracestate) {
+  if (typeof traceparent !== "string") return void 0;
+  const parts = traceparent.trim().split("-");
+  if (parts.length < 4) return void 0;
+  const [version, traceId, spanId, flagsHex] = parts;
+  if (version === void 0 || !VERSION_RE.test(version)) return void 0;
+  if (version === "ff") return void 0;
+  if (flagsHex === void 0 || !/^[0-9a-f]{2}$/.test(flagsHex)) {
+    return void 0;
+  }
+  const traceFlags = Number.parseInt(flagsHex, 16);
+  return normalizeTraceContext({
+    traceId,
+    spanId,
+    traceFlags,
+    ...typeof tracestate === "string" ? { traceState: tracestate } : {}
+  });
+}
+
 // src/transport/console-transport.ts
 function resolveConsoleMethod(level) {
   const slot = console[level];
@@ -1235,6 +1303,7 @@ exports.configureLogging = configureLogging;
 exports.createLogger = createLogger;
 exports.createRedactor = createRedactor;
 exports.getRootLogger = getRootLogger;
+exports.parseTraceparent = parseTraceparent;
 exports.scrubUrl = scrubUrl;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map