@logbrew/sdk 0.1.37 → 0.1.39

package/opentelemetry-bridge.cjs

@@ -0,0 +1,330 @@
+const { callableOrUndefined, errorHandler, settledFlush } = require("./capture-support.cjs");
+const { LogBrewClient } = require("./client.cjs");
+const { NULL_VALUE } = require("./null-value.cjs");
+const { resolveOpenTelemetryReadableSpanOptions } = require("./opentelemetry-keys.cjs");
+const { readableSpanAttributes } = require("./opentelemetry-span.cjs");
+const { OpenTelemetryTraceSummary } = require("./opentelemetry-summary.cjs");
+const { timestampFromOpenTelemetryReadableSpan } = require("./opentelemetry-time.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { isList, isRecord, isTruthy, requireNonEmpty } = require("./validation.cjs");
+
+/**
+ * @import { SpanAttributes } from "./index.cjs"
+ * @import { DeepReadonly } from "./validation.cjs"
+ * @typedef {InstanceType<typeof OpenTelemetryTraceSummary>} TraceSummary
+ * @import { ErrorHandler } from "./capture-support.cjs"
+ * @import { ResolvedSpanOptions } from "./opentelemetry-keys.cjs"
+ * @typedef {Readonly<{
+ *   span: (id: string, timestamp: unknown, attributes: Readonly<Record<string, unknown>>) => unknown,
+ *   flush: (transport: unknown) => unknown,
+ *   pendingEvents: () => number
+ * }>} SpanClient
+ * @typedef {Readonly<{
+ *   client: SpanClient,
+ *   eventIdPrefix: string,
+ *   flushEnabled: boolean,
+ *   includeTraceSummary: boolean,
+ *   onError: ErrorHandler,
+ *   resolvedOptions: ResolvedSpanOptions,
+ *   spanFilter: ((span: unknown) => unknown) | undefined,
+ *   timestamp: (() => unknown) | undefined,
+ *   transport: unknown
+ * }>} BridgeSettings
+ */
+
+const NO_PENDING_EVENTS = 0;
+const NO_TRACE_SUMMARIES = 0;
+const NO_SPANS = 0;
+const OTEL_EXPORT_RESULT_SUCCESS = 0;
+const OTEL_EXPORT_RESULT_FAILED = 1;
+
+/**
+ * @param {unknown} error
+ * @returns {{ code: number, error?: Error }}
+ */
+function openTelemetryExportFailure(error) {
+  return {
+    code: OTEL_EXPORT_RESULT_FAILED,
+    ...(error instanceof Error ? { error } : {})
+  };
+}
+
+/**
+ * @param {unknown} filter
+ * @returns {((span: unknown) => unknown) | undefined}
+ */
+function spanFilterOrUndefined(filter) {
+  if (typeof filter !== "function") {
+    return undefined;
+  }
+  return (span) => {
+    /** @type {unknown} */
+    const keep = Reflect.apply(filter, undefined, [span]);
+    return keep;
+  };
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} config
+ * @param {string} kind
+ * @returns {SpanClient}
+ */
+function bridgeClient(config, kind) {
+  const { client } = config;
+  if (!(client instanceof LogBrewClient)) {
+    throw new SdkError("validation_error", `OpenTelemetry span ${kind} client must be a LogBrewClient`);
+  }
+  return client;
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} config
+ * @param {string} kind
+ * @param {string} flushKey
+ * @returns {BridgeSettings}
+ */
+function bridgeSettings(config, kind, flushKey) {
+  const client = bridgeClient(config, kind);
+  const eventIdPrefix = requireNonEmpty("OpenTelemetry eventIdPrefix", config["eventIdPrefix"] ?? "otel");
+  const { transport } = config;
+  const timestamp = callableOrUndefined(config["timestamp"]);
+  const onError = errorHandler(config["onError"]);
+  const spanFilter = spanFilterOrUndefined(config["spanFilter"]);
+  const flushEnabled = config[flushKey] !== false;
+  const includeTraceSummary = config["includeTraceSummary"] === true;
+  const resolvedOptions = resolveOpenTelemetryReadableSpanOptions(config);
+  return { client, eventIdPrefix, flushEnabled, includeTraceSummary, onError, resolvedOptions, spanFilter, timestamp, transport };
+}
+
+class OpenTelemetryBridge {
+  captured = NO_SPANS;
+  closed = false;
+  flushInFlight = false;
+  /** @type {Promise<unknown>} */
+  pendingFlush = Promise.resolve(NULL_VALUE);
+  currentFlush = this.pendingFlush;
+  requestedFlush = this.pendingFlush;
+  /** @type {Promise<unknown> | undefined} */
+  queuedFlush = undefined;
+  traceSummaryCount = NO_TRACE_SUMMARIES;
+  /** @type {Map<string, TraceSummary>} */
+  traceSummaries = new Map();
+
+  /**
+   * @param {BridgeSettings} settings
+   * @param {boolean} swallowErrors
+   */
+  constructor(settings, swallowErrors) {
+    this.settings = settings;
+    this.swallowErrors = swallowErrors;
+  }
+
+  /**
+   * @param {unknown} span
+   * @returns {void}
+   */
+  enqueue(span) {
+    const { settings } = this;
+    if (settings.spanFilter?.(span) === false || !isRecord(span)) {
+      return;
+    }
+    const attributes = readableSpanAttributes(span, settings.resolvedOptions);
+    if (attributes === undefined) {
+      return;
+    }
+    this.recordTraceSummary(attributes, span);
+    this.captured += 1;
+    settings.client.span(
+      `${settings.eventIdPrefix}_${this.captured}`,
+      timestampFromOpenTelemetryReadableSpan(span, settings.timestamp),
+      attributes
+    );
+  }
+
+  /**
+   * @param {unknown} span
+   * @returns {void}
+   */
+  end(span) {
+    if (this.closed) {
+      return;
+    }
+    try {
+      this.enqueue(span);
+    } catch (error) {
+      this.settings.onError(error);
+    }
+  }
+
+  /**
+   * @param {DeepReadonly<SpanAttributes>} attributes
+   * @param {Readonly<Record<string, unknown>>} span
+   * @returns {void}
+   */
+  recordTraceSummary(attributes, span) {
+    if (!this.settings.includeTraceSummary) {
+      return;
+    }
+    let summary = this.traceSummaries.get(attributes.traceId);
+    if (summary === undefined) {
+      summary = new OpenTelemetryTraceSummary(attributes.traceId);
+      this.traceSummaries.set(attributes.traceId, summary);
+    }
+    summary.record(attributes, span);
+  }
+
+  /**
+   * @returns {void}
+   */
+  enqueueTraceSummaries() {
+    if (this.traceSummaries.size === NO_TRACE_SUMMARIES) {
+      return;
+    }
+    const { settings } = this;
+    const summaries = [...this.traceSummaries.values()];
+    this.traceSummaries.clear();
+    for (const summary of summaries) {
+      try {
+        this.traceSummaryCount += 1;
+        settings.client.span(
+          `${settings.eventIdPrefix}_trace_${this.traceSummaryCount}`,
+          summary.timestamp(settings.timestamp),
+          summary.attributes()
+        );
+      } catch (error) {
+        settings.onError(error);
+      }
+    }
+  }
+
+  /**
+   * @param {boolean} flushEnabled
+   * @returns {Promise<void>}
+   */
+  async flushQueue(flushEnabled) {
+    const { settings } = this;
+    if (settings.includeTraceSummary) {
+      this.enqueueTraceSummaries();
+    }
+    if (!isTruthy(settings.transport) || !flushEnabled || settings.client.pendingEvents() === NO_PENDING_EVENTS) {
+      await this.pendingFlush;
+      return;
+    }
+    this.requestFlush();
+    await this.requestedFlush;
+  }
+
+  /**
+   * @returns {void}
+   */
+  requestFlush() {
+    if (this.flushInFlight) {
+      this.queuedFlush ??= this.flushAfter(this.currentFlush);
+      this.requestedFlush = this.queuedFlush;
+      return;
+    }
+    this.startFlush();
+  }
+
+  /**
+   * @returns {void}
+   */
+  startFlush() {
+    const { settings } = this;
+    this.flushInFlight = true;
+    const rawFlush = Promise.resolve(settings.client.flush(settings.transport));
+    this.currentFlush = rawFlush;
+    this.pendingFlush = this.swallowErrors ? settledFlush(rawFlush, settings.onError) : rawFlush;
+    this.requestedFlush = this.pendingFlush;
+    void this.settle(rawFlush);
+  }
+
+  /**
+   * @param {unknown} rawFlush
+   * @returns {Promise<void>}
+   */
+  async settle(rawFlush) {
+    try {
+      await rawFlush;
+    } catch {
+      this.finishFlush();
+      return;
+    }
+    this.finishFlush();
+  }
+
+  /**
+   * @returns {void}
+   */
+  finishFlush() {
+    this.flushInFlight = false;
+    this.queuedFlush = undefined;
+  }
+
+  /**
+   * @param {unknown} inFlight
+   * @returns {Promise<unknown>}
+   */
+  async flushAfter(inFlight) {
+    try {
+      await inFlight;
+    } catch (error) {
+      if (this.swallowErrors) {
+        return NULL_VALUE;
+      }
+      throw error;
+    }
+    this.requestFlush();
+    const result = await this.requestedFlush;
+    return result;
+  }
+
+  /**
+   * @param {unknown} spans
+   * @returns {{ error: unknown } | undefined}
+   */
+  enqueueExport(spans) {
+    if (this.closed) {
+      return { error: new SdkError("shutdown_error", "OpenTelemetry span exporter is already shut down") };
+    }
+    if (!isList(spans)) {
+      const error = new SdkError("validation_error", "OpenTelemetry span exporter spans must be an array");
+      this.settings.onError(error);
+      return { error };
+    }
+    return this.enqueueAll(spans);
+  }
+
+  /**
+   * @param {readonly unknown[]} spans
+   * @returns {{ error: unknown } | undefined}
+   */
+  enqueueAll(spans) {
+    try {
+      for (const span of spans) {
+        this.enqueue(span);
+      }
+    } catch (error) {
+      this.settings.onError(error);
+      return { error };
+    }
+    return undefined;
+  }
+
+  /**
+   * @param {(result: unknown) => void} report
+   * @returns {Promise<void>}
+   */
+  async reportExport(report) {
+    try {
+      await this.flushQueue(this.settings.flushEnabled);
+    } catch (error) {
+      this.settings.onError(error);
+      report(openTelemetryExportFailure(error));
+      return;
+    }
+    report({ code: OTEL_EXPORT_RESULT_SUCCESS });
+  }
+}
+
+module.exports = { OpenTelemetryBridge, bridgeSettings, openTelemetryExportFailure };

package/opentelemetry-context.cjs

@@ -0,0 +1,245 @@
+const { NULL_VALUE } = require("./null-value.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const {
+  ZERO_SPAN_ID,
+  isObjectValue,
+  optionalProperty,
+  requireSpanId,
+  requireTraceId
+} = require("./validation.cjs");
+
+/**
+ * @import { LogCorrelationTraceContext } from "./index.cjs"
+ * @typedef {{ traceId: string, spanId: string, sampled: boolean }} SpanContextIds
+ * @typedef {Readonly<{ spanId?: unknown, spanIdFactory?: unknown }>} ChildSpanOptions
+ */
+
+const SPAN_ID_BYTES = 8;
+const MAX_SPAN_ID_ATTEMPTS = 3;
+const FIRST_ATTEMPT = 0;
+const ATTEMPT_STEP = 1;
+const BYTE_VALUES = 256;
+const HEX_RADIX = 16;
+const HEX_BYTE_WIDTH = 2;
+const SAMPLED_BIT_BASE = 2;
+const SAMPLED_BIT = 1;
+const OPENTELEMETRY_API_PACKAGE = "@opentelemetry/api";
+
+/**
+ * @param {unknown} traceId
+ * @returns {string | undefined}
+ */
+function normalizeTraceId(traceId) {
+  try {
+    return requireTraceId(traceId).toLowerCase();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {unknown} spanId
+ * @returns {string | undefined}
+ */
+function normalizeSpanId(spanId) {
+  try {
+    return requireSpanId("trace spanId", spanId).toLowerCase();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {unknown} traceFlags
+ * @returns {boolean}
+ */
+function openTelemetryTraceFlagsSampled(traceFlags) {
+  const sampled = optionalProperty(traceFlags, "sampled");
+  if (typeof sampled === "boolean") {
+    return sampled;
+  }
+  if (typeof traceFlags === "number" && Number.isFinite(traceFlags)) {
+    return Math.abs(Math.trunc(traceFlags) % SAMPLED_BIT_BASE) === SAMPLED_BIT;
+  }
+  return false;
+}
+
+/**
+ * @param {unknown} spanContext
+ * @returns {SpanContextIds | undefined}
+ */
+function normalizeOpenTelemetrySpanContextIds(spanContext) {
+  if (!isObjectValue(spanContext) || spanContext["isValid"] === false) {
+    return undefined;
+  }
+  const traceId = normalizeTraceId(spanContext["traceId"]);
+  const spanId = normalizeSpanId(spanContext["spanId"]);
+  if (traceId === undefined || spanId === undefined) {
+    return undefined;
+  }
+  return {
+    traceId,
+
+    spanId,
+
+    sampled: openTelemetryTraceFlagsSampled(spanContext["traceFlags"])
+  };
+}
+
+/**
+ * @param {number} byteLength
+ * @returns {string}
+ */
+function randomHex(byteLength) {
+  const bytes = new Uint8Array(byteLength);
+  const crypto = optionalProperty(globalThis, "crypto");
+  const getRandomValues = optionalProperty(crypto, "getRandomValues");
+  if (typeof getRandomValues === "function") {
+    Reflect.apply(getRandomValues, crypto, [bytes]);
+  } else {
+    for (const index of bytes.keys()) {
+      bytes[index] = Math.floor(Math.random() * BYTE_VALUES);
+    }
+  }
+  return Array.from(bytes, (byte) => byte.toString(HEX_RADIX).padStart(HEX_BYTE_WIDTH, "0")).join("");
+}
+
+/**
+ * @returns {string}
+ */
+function defaultSpanIdFactory() {
+  for (let attempt = FIRST_ATTEMPT; attempt < MAX_SPAN_ID_ATTEMPTS; attempt += ATTEMPT_STEP) {
+    const spanId = randomHex(SPAN_ID_BYTES);
+    if (spanId !== ZERO_SPAN_ID) {
+      return spanId;
+    }
+  }
+  throw new SdkError("configuration_error", "spanIdFactory must return a non-zero 16-character hex span id");
+}
+
+/**
+ * @param {ChildSpanOptions} [options]
+ * @returns {string}
+ */
+function resolveLogBrewChildSpanId(options = {}) {
+  const explicitSpanId = options.spanId;
+  if (explicitSpanId !== undefined) {
+    return requireSpanId("spanId", explicitSpanId).toLowerCase();
+  }
+  const { spanIdFactory } = options;
+  /** @type {unknown} */
+  const spanId = typeof spanIdFactory === "function"
+    ? Reflect.apply(spanIdFactory, undefined, [])
+    : defaultSpanIdFactory();
+  return requireSpanId("spanId", spanId).toLowerCase();
+}
+
+/**
+ * @param {unknown} method
+ * @param {unknown} thisArg
+ * @returns {{ value: unknown } | undefined}
+ */
+function callWithoutArguments(method, thisArg) {
+  if (typeof method !== "function") {
+    return undefined;
+  }
+  try {
+    return { value: Reflect.apply(method, thisArg, []) };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {unknown} spanContext
+ * @param {ChildSpanOptions} [options]
+ * @returns {LogCorrelationTraceContext | null}
+ */
+function logbrewTraceContextFromOpenTelemetrySpanContext(spanContext, options = {}) {
+  const context = normalizeOpenTelemetrySpanContextIds(spanContext);
+  if (context === undefined) {
+    return NULL_VALUE;
+  }
+  return {
+    traceId: context.traceId,
+
+    spanId: resolveLogBrewChildSpanId(options),
+
+    parentSpanId: context.spanId,
+    sampled: context.sampled
+  };
+}
+
+/**
+ * @param {unknown} span
+ * @param {ChildSpanOptions} [options]
+ * @returns {LogCorrelationTraceContext | null}
+ */
+function logbrewTraceContextFromOpenTelemetrySpan(span, options = {}) {
+  if (!isObjectValue(span)) {
+    return NULL_VALUE;
+  }
+  const getSpanContext = typeof span["spanContext"] === "function"
+    ? span["spanContext"]
+    : span["getSpanContext"];
+  const spanContext = callWithoutArguments(getSpanContext, span);
+  if (spanContext === undefined) {
+    return NULL_VALUE;
+  }
+  return logbrewTraceContextFromOpenTelemetrySpanContext(spanContext.value, options);
+}
+
+/**
+ * @returns {((id: string) => unknown) | undefined}
+ */
+function optionalRequire() {
+  /** @type {unknown} */
+  const moduleRequire = typeof module === "undefined" ? undefined : Reflect.get(module, "require");
+  if (typeof moduleRequire === "function") {
+    return (id) => {
+      /** @type {unknown} */
+      const required = Reflect.apply(moduleRequire, module, [id]);
+      return required;
+    };
+  }
+  return typeof require === "function" ? require : undefined;
+}
+
+/**
+ * @returns {unknown}
+ */
+function optionalOpenTelemetryApi() {
+  const requireOptional = optionalRequire();
+  if (requireOptional === undefined) {
+    return undefined;
+  }
+  try {
+    return requireOptional(OPENTELEMETRY_API_PACKAGE);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {ChildSpanOptions} [options]
+ * @returns {LogCorrelationTraceContext | null}
+ */
+function logbrewTraceContextFromCurrentOpenTelemetrySpan(options = {}) {
+  const openTelemetryApi = optionalProperty(options, "openTelemetryApi") ?? optionalOpenTelemetryApi();
+  const trace = optionalProperty(openTelemetryApi, "trace");
+  const getActiveSpan = optionalProperty(trace, "getActiveSpan");
+  const activeSpan = callWithoutArguments(getActiveSpan, trace);
+  if (activeSpan === undefined) {
+    return NULL_VALUE;
+  }
+  return logbrewTraceContextFromOpenTelemetrySpan(activeSpan.value, options);
+}
+
+module.exports = {
+  defaultSpanIdFactory,
+  logbrewTraceContextFromCurrentOpenTelemetrySpan,
+  logbrewTraceContextFromOpenTelemetrySpan,
+  logbrewTraceContextFromOpenTelemetrySpanContext,
+  normalizeOpenTelemetrySpanContextIds,
+  normalizeSpanId
+};

package/opentelemetry-exceptions.cjs

@@ -0,0 +1,69 @@
+const { isList, isRecord, optionalProperty } = require("./validation.cjs");
+
+/**
+ * @import { Metadata } from "./index.cjs"
+ */
+
+const MAX_EXCEPTION_TYPES = 8;
+const NO_EXCEPTIONS = 0;
+const EXCEPTION_TYPE_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$:.]{0,127}$/u;
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function safeOpenTelemetryExceptionType(value) {
+  return typeof value === "string" && EXCEPTION_TYPE_PATTERN.test(value) ? value : undefined;
+}
+
+class OpenTelemetryExceptionSummary {
+  count = NO_EXCEPTIONS;
+  escapedCount = NO_EXCEPTIONS;
+  /** @type {string[]} */
+  types = [];
+
+  /**
+   * @param {Readonly<Record<string, unknown>>} event
+   * @returns {void}
+   */
+  add(event) {
+    this.count += 1;
+    if (optionalProperty(event["attributes"], "exception.escaped") === true) {
+      this.escapedCount += 1;
+    }
+    const type = safeOpenTelemetryExceptionType(optionalProperty(event["attributes"], "exception.type"));
+    if (type !== undefined && !this.types.includes(type) && this.types.length < MAX_EXCEPTION_TYPES) {
+      this.types.push(type);
+    }
+  }
+
+  /**
+   * @returns {Metadata}
+   */
+  metadata() {
+    return {
+      "otel.exception_event_count": this.count,
+      ...(this.escapedCount > NO_EXCEPTIONS ? { "otel.exception_escaped_count": this.escapedCount } : {}),
+      ...(this.types.length > NO_EXCEPTIONS ? { "otel.exception_types": this.types.join(",") } : {})
+    };
+  }
+}
+
+/**
+ * @param {unknown} events
+ * @returns {OpenTelemetryExceptionSummary | undefined}
+ */
+function openTelemetryExceptionEventSummary(events) {
+  if (!isList(events) || events.length === NO_EXCEPTIONS) {
+    return undefined;
+  }
+  const summary = new OpenTelemetryExceptionSummary();
+  for (const event of events) {
+    if (isRecord(event) && event["name"] === "exception") {
+      summary.add(event);
+    }
+  }
+  return summary.count > NO_EXCEPTIONS ? summary : undefined;
+}
+
+module.exports = { openTelemetryExceptionEventSummary, safeOpenTelemetryExceptionType };