@logbrew/sdk 0.1.38 → 0.1.39

package/index.js

@@ -36,4 +36,4 @@ export const {
   TransportError
 } = sdk;
 
-export default sdk;
+export { default } from "./index.cjs";

package/issue-exception.cjs

@@ -73,12 +73,9 @@ function validateIssueExceptionMechanism(mechanism) {
 
 /**
  * @param {unknown} exception
- * @returns {IssueException | undefined}
+ * @returns {IssueException}
  */
-function validateIssueException(exception) {
-  if (exception === undefined) {
-    return undefined;
-  }
+function requireIssueException(exception) {
   const source = requireObject("issue exception", exception);
   rejectUnknownKeys("issue exception", source, EXCEPTION_KEYS);
   const type = boundedIdentity("issue exception type", source["type"], MAX_EXCEPTION_TYPE_LENGTH);
@@ -86,14 +83,22 @@ function validateIssueException(exception) {
   return { type, ...optionalEntry("mechanism", mechanism) };
 }
 
+/**
+ * @param {unknown} exception
+ * @returns {IssueException | undefined}
+ */
+function validateIssueException(exception) {
+  return exception === undefined ? undefined : requireIssueException(exception);
+}
+
 /**
  * @param {string} type
  * @param {string} mechanism
- * @param {boolean} handled
- * @returns {IssueException | undefined}
+ * @param {unknown} handled
+ * @returns {IssueException}
  */
 function createIssueException(type, mechanism, handled) {
-  return validateIssueException({ mechanism: { handled, type: mechanism }, type });
+  return requireIssueException({ mechanism: { handled, type: mechanism }, type });
 }
 
 /**

package/metric-validation.cjs

@@ -0,0 +1,95 @@
+const { withMetadata } = require("./event-metadata.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { hasUnicodeControlCharacter, optionalEntry, requireAllowedValue, requireFiniteNumber, requireNonEmpty } = require("./validation.cjs");
+
+/**
+ * @import { EventAttributes } from "./event-validation.cjs"
+ * @typedef {"counter" | "gauge" | "histogram"} MetricKind
+ */
+
+const MAX_METRIC_DESCRIPTION_LENGTH = 1024;
+const MIN_METRIC_VALUE = 0;
+const FIRST_CODE_POINT = 0;
+const FIRST_SURROGATE = 0xD8_00;
+const LAST_SURROGATE = 0xDF_FF;
+const LINE_SEPARATOR = 0x20_28;
+const PARAGRAPH_SEPARATOR = 0x20_29;
+/** @type {ReadonlySet<MetricKind>} */
+const METRIC_KINDS = new Set(["counter", "gauge", "histogram"]);
+/** @type {ReadonlySet<MetricKind>} */
+const NON_NEGATIVE_METRIC_KINDS = new Set(["counter", "histogram"]);
+/** @type {ReadonlySet<string>} */
+const CUMULATIVE_TEMPORALITIES = new Set(["delta", "cumulative"]);
+/** @type {ReadonlyMap<MetricKind, ReadonlySet<string>>} */
+const METRIC_TEMPORALITIES_BY_KIND = new Map([
+  ["counter", CUMULATIVE_TEMPORALITIES],
+  ["gauge", new Set(["instant"])],
+  ["histogram", CUMULATIVE_TEMPORALITIES]
+]);
+
+/**
+ * @param {string} character
+ * @returns {boolean}
+ */
+function isSeparatorOrSurrogate(character) {
+  const code = character.codePointAt(FIRST_CODE_POINT);
+  return code !== undefined && (
+    (code >= FIRST_SURROGATE && code <= LAST_SURROGATE)
+    || code === LINE_SEPARATOR
+    || code === PARAGRAPH_SEPARATOR
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function metricDescriptionOrUndefined(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  const characters = typeof value === "string" ? [...value] : [];
+  if (
+    typeof value !== "string"
+    || value.trim() === ""
+    || characters.length > MAX_METRIC_DESCRIPTION_LENGTH
+    || hasUnicodeControlCharacter(value)
+    || characters.some((character) => isSeparatorOrSurrogate(character))
+  ) {
+    throw new SdkError(
+      "validation_error",
+      `metric description must be a non-blank string of at most ${MAX_METRIC_DESCRIPTION_LENGTH} non-control characters`
+    );
+  }
+  return value.trim();
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} attributes
+ * @returns {EventAttributes}
+ */
+function validateMetric(attributes) {
+  const name = requireNonEmpty("metric name", attributes["name"]);
+  const kind = requireAllowedValue("metric kind", attributes["kind"], METRIC_KINDS);
+  const value = requireFiniteNumber("metric value", attributes["value"]);
+  const unit = requireNonEmpty("metric unit", attributes["unit"]);
+  const allowedTemporalities = METRIC_TEMPORALITIES_BY_KIND.get(kind) ?? CUMULATIVE_TEMPORALITIES;
+  const temporality = requireAllowedValue(`metric temporality for ${kind}`, attributes["temporality"], allowedTemporalities);
+  if (NON_NEGATIVE_METRIC_KINDS.has(kind) && value < MIN_METRIC_VALUE) {
+    throw new SdkError("validation_error", `metric ${kind} value must be non-negative`);
+  }
+  const description = metricDescriptionOrUndefined(attributes["description"]);
+  return withMetadata({
+    name,
+    ...optionalEntry("description", description),
+    kind,
+
+    value,
+
+    unit,
+
+    temporality
+  }, attributes["metadata"], attributes["context"]);
+}
+
+module.exports = { validateMetric };

package/network-milestone.cjs

@@ -0,0 +1,155 @@
+const { ACTION_STATUSES } = require("./event-validation.cjs");
+const { compactMetadata } = require("./log-context.cjs");
+const { sanitizeRouteTemplate } = require("./product-action.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { isRecord, requireAllowedValue, requireNonEmpty, stringOrUndefined } = require("./validation.cjs");
+
+/**
+ * @import { ActionStatus, TimelineAttributes, TimelineOptions } from "./product-action.cjs"
+ * @typedef {{
+ *   durationMs: number | undefined,
+ *   metadata: unknown,
+ *   method: string,
+ *   name: string,
+ *   routeTemplate: string,
+ *   sessionId: unknown,
+ *   status: ActionStatus,
+ *   statusCode: number | undefined,
+ *   traceId: unknown
+ * }} NetworkMilestoneDetails
+ */
+
+const MIN_STATUS_CODE = 100;
+const MAX_STATUS_CODE = 599;
+const FAILURE_STATUS_CODE = 400;
+const MIN_DURATION_MS = 0;
+const HTTP_METHOD_PATTERN = /^[A-Z][A-Z0-9_-]*$/u;
+
+/**
+ * @param {unknown} method
+ * @returns {string}
+ */
+function normalizeHttpMethod(method) {
+  const value = method === undefined ? "GET" : method;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new SdkError("validation_error", "network milestone method must be a non-empty string");
+  }
+  const normalized = value.trim().toUpperCase();
+  if (!HTTP_METHOD_PATTERN.test(normalized)) {
+    throw new SdkError("validation_error", "network milestone method must be a valid HTTP method");
+  }
+  return normalized;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function statusCodeOrUndefined(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "number" || !Number.isInteger(value) || value < MIN_STATUS_CODE || value > MAX_STATUS_CODE) {
+    throw new SdkError("validation_error", "network milestone statusCode must be an integer from 100 to 599");
+  }
+  return value;
+}
+
+/**
+ * @param {string} label
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function nonNegativeNumberOrUndefined(label, value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value < MIN_DURATION_MS) {
+    throw new SdkError("validation_error", `${label} must be a non-negative number`);
+  }
+  return value;
+}
+
+/**
+ * @param {number | undefined} statusCode
+ * @returns {"failure" | "success"}
+ */
+function statusFromStatusCode(statusCode) {
+  return statusCode !== undefined && statusCode >= FAILURE_STATUS_CODE ? "failure" : "success";
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} request
+ * @returns {NetworkMilestoneDetails}
+ */
+function networkMilestoneFields(request) {
+  const routeTemplate = requireNonEmpty("network milestone routeTemplate", sanitizeRouteTemplate(request["routeTemplate"]));
+  const method = normalizeHttpMethod(request["method"]);
+  const statusCode = statusCodeOrUndefined(request["statusCode"]);
+  const requestedStatus = request["status"];
+  const status = requireAllowedValue(
+    "network milestone status",
+    requestedStatus === undefined ? statusFromStatusCode(statusCode) : requestedStatus,
+    ACTION_STATUSES
+  );
+  const durationMs = nonNegativeNumberOrUndefined("network milestone durationMs", request["durationMs"]);
+  const name = stringOrUndefined(request["name"]) ?? `network.${method.toLowerCase()} ${routeTemplate}`;
+  return {
+    durationMs,
+    metadata: request["metadata"],
+    method,
+    name,
+    routeTemplate,
+    sessionId: request["sessionId"],
+    status,
+    statusCode,
+    traceId: request["traceId"]
+  };
+}
+
+/**
+ * @param {unknown} request
+ * @returns {NetworkMilestoneDetails}
+ */
+function networkMilestoneDetails(request) {
+  if (typeof request === "string") {
+    return networkMilestoneFields({ routeTemplate: request });
+  }
+  if (!isRecord(request)) {
+    throw new SdkError("validation_error", "network milestone must be a string or object");
+  }
+  return networkMilestoneFields(request);
+}
+
+/**
+ * @param {unknown} request
+ * @param {TimelineOptions} [options]
+ * @returns {TimelineAttributes}
+ */
+function createNetworkMilestoneAttributes(request, options = {}) {
+  const details = networkMilestoneDetails(request);
+  return {
+    name: details.name,
+
+    status: details.status,
+
+    metadata: compactMetadata({
+      source: "network.milestone",
+      ...compactMetadata(options.metadata),
+      ...compactMetadata(details.metadata),
+      routeTemplate: details.routeTemplate,
+
+      method: details.method,
+
+      statusCode: details.statusCode,
+
+      durationMs: details.durationMs,
+
+      sessionId: stringOrUndefined(details.sessionId),
+
+      traceId: stringOrUndefined(details.traceId)
+    })
+  };
+}
+
+module.exports = { createNetworkMilestoneAttributes };

package/null-value.cjs

@@ -0,0 +1,4 @@
+/** @type {null} */
+const NULL_VALUE = null;
+
+module.exports = { NULL_VALUE };

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 };