@logbrew/sdk 0.1.38 → 0.1.39

package/opentelemetry-span.cjs

@@ -0,0 +1,286 @@
+const { NULL_VALUE } = require("./null-value.cjs");
+const {
+  normalizeOpenTelemetrySpanContextIds,
+  normalizeSpanId
+} = require("./opentelemetry-context.cjs");
+const { openTelemetryExceptionEventSummary } = require("./opentelemetry-exceptions.cjs");
+const {
+  openTelemetrySelectedMetadata,
+  resolveOpenTelemetryReadableSpanOptions
+} = require("./opentelemetry-keys.cjs");
+const { durationMsFromOpenTelemetryReadableSpan, timestampFromOpenTelemetryTime } = require("./opentelemetry-time.cjs");
+const { isList, isRecord, optionalProperty, stringOrUndefined } = require("./validation.cjs");
+
+/**
+ * @import { Metadata, SpanAttributes, SpanEventSummary, SpanLinkSummary } from "./index.cjs"
+ * @import { ReadableSpanOptions, ResolvedSpanOptions } from "./opentelemetry-keys.cjs"
+ * @typedef {Readonly<Record<string, unknown>>} ReadableSpan
+ * @typedef {{ traceId: string, spanId: string, parentSpanId?: string, sampled: boolean }} ReadableSpanContext
+ */
+
+const MAX_SPAN_EVENTS = 8;
+const MAX_SPAN_LINKS = 8;
+const FIRST_ITEM = 0;
+const EMPTY = 0;
+const OTEL_STATUS_CODE_ERROR = 2;
+const OTEL_STATUS_CODE_OK = 1;
+const SPAN_KIND_INTERNAL = 0;
+const SPAN_KIND_SERVER = 1;
+const SPAN_KIND_CLIENT = 2;
+const SPAN_KIND_PRODUCER = 3;
+const SPAN_KIND_CONSUMER = 4;
+/** @type {ReadonlyMap<unknown, string>} */
+const OTEL_SPAN_KIND_NAMES = new Map([
+  [SPAN_KIND_INTERNAL, "internal"],
+  [SPAN_KIND_SERVER, "server"],
+  [SPAN_KIND_CLIENT, "client"],
+  [SPAN_KIND_PRODUCER, "producer"],
+  [SPAN_KIND_CONSUMER, "consumer"]
+]);
+
+/**
+ * @param {ReadableSpan} span
+ * @returns {unknown}
+ */
+function readOpenTelemetrySpanContext(span) {
+  const { spanContext } = span;
+  if (typeof spanContext !== "function") {
+    return undefined;
+  }
+  try {
+    return Reflect.apply(spanContext, span, []);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * @param {ReadableSpan} span
+ * @returns {ReadableSpanContext | undefined}
+ */
+function normalizeOpenTelemetryReadableSpanContext(span) {
+  const context = normalizeOpenTelemetrySpanContextIds(readOpenTelemetrySpanContext(span));
+  if (context === undefined) {
+    return undefined;
+  }
+  const parentContext = normalizeOpenTelemetrySpanContextIds(span["parentSpanContext"]);
+  const parentSpanId = parentContext?.traceId === context.traceId
+    ? parentContext.spanId
+    : normalizeSpanId(span["parentSpanId"]);
+  return {
+    traceId: context.traceId,
+
+    spanId: context.spanId,
+    ...(parentSpanId === undefined ? {} : { parentSpanId }),
+    sampled: context.sampled
+  };
+}
+
+/**
+ * @param {unknown} kind
+ * @returns {string | undefined}
+ */
+function openTelemetrySpanKindName(kind) {
+  if (typeof kind === "number") {
+    return OTEL_SPAN_KIND_NAMES.get(kind);
+  }
+  if (typeof kind === "string" && kind.trim() !== "") {
+    return kind.toLowerCase();
+  }
+  return undefined;
+}
+
+/**
+ * @param {string} key
+ * @param {unknown} value
+ * @returns {Metadata}
+ */
+function positiveOpenTelemetryCount(key, value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > EMPTY ? { [key]: value } : {};
+}
+
+/**
+ * @param {string} key
+ * @param {string | undefined} value
+ * @returns {Metadata}
+ */
+function definedEntry(key, value) {
+  return value === undefined ? {} : { [key]: value };
+}
+
+/**
+ * @param {ReadableSpan} span
+ * @param {ResolvedSpanOptions} options
+ * @returns {Metadata}
+ */
+function openTelemetryReadableSpanMetadata(span, options) {
+  const resource = openTelemetrySelectedMetadata(optionalProperty(span["resource"], "attributes"), options.resourceAttributeKeys);
+  const kind = openTelemetrySpanKindName(span["kind"]);
+  const scopeName = stringOrUndefined(optionalProperty(span["instrumentationScope"], "name"));
+  const scopeVersion = stringOrUndefined(optionalProperty(span["instrumentationScope"], "version"));
+  return {
+    source: "opentelemetry.readable_span",
+    ...options.metadata,
+    ...resource,
+    ...definedEntry("otel.kind", kind),
+    ...definedEntry("otel.scope.name", scopeName),
+    ...definedEntry("otel.scope.version", scopeVersion),
+    ...positiveOpenTelemetryCount("otel.dropped_attributes_count", span["droppedAttributesCount"]),
+    ...positiveOpenTelemetryCount("otel.dropped_events_count", span["droppedEventsCount"]),
+    ...positiveOpenTelemetryCount("otel.dropped_links_count", span["droppedLinksCount"]),
+    ...openTelemetrySelectedMetadata(span["attributes"], options.attributeKeys)
+  };
+}
+
+/**
+ * @param {Readonly<Record<string, unknown>>} event
+ * @param {ResolvedSpanOptions} options
+ * @returns {SpanEventSummary}
+ */
+function openTelemetryEventSummary(event, options) {
+  const eventName = event["name"];
+  const name = typeof eventName === "string" && eventName.trim() !== "" ? eventName : "opentelemetry.event";
+  const timestamp = timestampFromOpenTelemetryTime(event["time"] ?? event["timestamp"]);
+  const metadata = openTelemetrySelectedMetadata(event["attributes"], options.eventAttributeKeys);
+  return {
+    name,
+    ...(timestamp === undefined ? {} : { timestamp }),
+    ...(Object.keys(metadata).length > EMPTY ? { metadata } : {})
+  };
+}
+
+/**
+ * @param {unknown} events
+ * @param {ResolvedSpanOptions} options
+ * @returns {SpanEventSummary[] | undefined}
+ */
+function openTelemetryReadableSpanEvents(events, options) {
+  if (!isList(events) || events.length === EMPTY) {
+    return undefined;
+  }
+  /** @type {SpanEventSummary[]} */
+  const summaries = [];
+  for (const event of events.slice(FIRST_ITEM, MAX_SPAN_EVENTS)) {
+    if (isRecord(event)) {
+      summaries.push(openTelemetryEventSummary(event, options));
+    }
+  }
+  return summaries.length > EMPTY ? summaries : undefined;
+}
+
+/**
+ * @param {unknown} link
+ * @param {ResolvedSpanOptions} options
+ * @returns {SpanLinkSummary | undefined}
+ */
+function openTelemetryLinkSummary(link, options) {
+  const context = normalizeOpenTelemetrySpanContextIds(
+    optionalProperty(link, "context") ?? optionalProperty(link, "spanContext")
+  );
+  if (context === undefined) {
+    return undefined;
+  }
+  const metadata = openTelemetrySelectedMetadata(optionalProperty(link, "attributes"), options.linkAttributeKeys);
+  return {
+    traceId: context.traceId,
+
+    spanId: context.spanId,
+
+    sampled: context.sampled,
+    ...(Object.keys(metadata).length > EMPTY ? { metadata } : {})
+  };
+}
+
+/**
+ * @param {unknown} links
+ * @param {ResolvedSpanOptions} options
+ * @returns {SpanLinkSummary[] | undefined}
+ */
+function openTelemetryReadableSpanLinks(links, options) {
+  if (!isList(links) || links.length === EMPTY) {
+    return undefined;
+  }
+  /** @type {SpanLinkSummary[]} */
+  const summaries = [];
+  for (const link of links.slice(FIRST_ITEM, MAX_SPAN_LINKS)) {
+    const summary = openTelemetryLinkSummary(link, options);
+    if (summary !== undefined) {
+      summaries.push(summary);
+    }
+  }
+  return summaries.length > EMPTY ? summaries : undefined;
+}
+
+/**
+ * @param {ReadableSpan} span
+ * @returns {string}
+ */
+function openTelemetrySpanName(span) {
+  const { name } = span;
+  return typeof name === "string" && name.trim() !== "" ? name : "opentelemetry.span";
+}
+
+/**
+ * @param {unknown} status
+ * @param {number} escapedExceptions
+ * @returns {"ok" | "error"}
+ */
+function openTelemetrySpanStatus(status, escapedExceptions) {
+  const code = optionalProperty(status, "code");
+  if (code === OTEL_STATUS_CODE_ERROR || code === "ERROR") {
+    return "error";
+  }
+  if (code === OTEL_STATUS_CODE_OK || code === "OK") {
+    return "ok";
+  }
+  if (escapedExceptions > EMPTY) {
+    return "error";
+  }
+  return "ok";
+}
+
+/**
+ * @param {ReadableSpan} span
+ * @param {ResolvedSpanOptions} options
+ * @returns {SpanAttributes | undefined}
+ */
+function readableSpanAttributes(span, options) {
+  const context = normalizeOpenTelemetryReadableSpanContext(span);
+  if (context === undefined || (!options.captureUnsampled && !context.sampled)) {
+    return undefined;
+  }
+  const metadata = openTelemetryReadableSpanMetadata(span, options);
+  const events = options.includeSpanEvents ? openTelemetryReadableSpanEvents(span["events"], options) : undefined;
+  const links = options.includeSpanLinks ? openTelemetryReadableSpanLinks(span["links"], options) : undefined;
+  const exceptionSummary = openTelemetryExceptionEventSummary(span["events"]);
+  const durationMs = durationMsFromOpenTelemetryReadableSpan(span);
+  const resolvedMetadata = { ...metadata, ...exceptionSummary?.metadata() };
+  return {
+    name: openTelemetrySpanName(span),
+
+    traceId: context.traceId,
+
+    spanId: context.spanId,
+    ...(context.parentSpanId === undefined ? {} : { parentSpanId: context.parentSpanId }),
+    status: openTelemetrySpanStatus(span["status"], exceptionSummary?.escapedCount ?? EMPTY),
+    ...(durationMs === undefined ? {} : { durationMs }),
+    ...(events === undefined ? {} : { events }),
+    ...(links === undefined ? {} : { links }),
+    ...(Object.keys(resolvedMetadata).length > EMPTY ? { metadata: resolvedMetadata } : {})
+  };
+}
+
+/**
+ * @param {unknown} span
+ * @param {ReadableSpanOptions} [options]
+ * @returns {SpanAttributes | null}
+ */
+function spanAttributesFromOpenTelemetryReadableSpan(span, options = {}) {
+  const resolvedOptions = resolveOpenTelemetryReadableSpanOptions(options);
+  if (!isRecord(span)) {
+    return NULL_VALUE;
+  }
+  return readableSpanAttributes(span, resolvedOptions) ?? NULL_VALUE;
+}
+
+module.exports = { readableSpanAttributes, spanAttributesFromOpenTelemetryReadableSpan };

package/opentelemetry-summary.cjs

@@ -0,0 +1,213 @@
+const { compactMetadata, isMetadataValue } = require("./log-context.cjs");
+const { defaultSpanIdFactory } = require("./opentelemetry-context.cjs");
+const { safeOpenTelemetryExceptionType } = require("./opentelemetry-exceptions.cjs");
+const { TRACE_SUMMARY_METADATA_KEYS } = require("./opentelemetry-keys.cjs");
+const {
+  endMsFromOpenTelemetryReadableSpan,
+  fallbackTimestampValue,
+  openTelemetryTimeMs,
+  timestampFromOpenTelemetryTime
+} = require("./opentelemetry-time.cjs");
+const { isTruthy } = require("./validation.cjs");
+
+/**
+ * @import { Metadata, MetadataValue, SpanAttributes } from "./index.cjs"
+ * @import { DeepReadonly } from "./validation.cjs"
+ * @typedef {DeepReadonly<SpanAttributes>} ReadonlySpanAttributes
+ */
+
+const NONE = 0;
+
+/**
+ * @param {Readonly<Metadata> | undefined} metadata
+ * @param {string} key
+ * @returns {number}
+ */
+function positiveSafeInteger(metadata, key) {
+  const value = metadata?.[key];
+  return typeof value === "number" && Number.isSafeInteger(value) && value > NONE ? value : NONE;
+}
+
+class OpenTelemetryTraceSummary {
+  spanCount = NONE;
+  errorSpanCount = NONE;
+  /** @type {Metadata} */
+  metadata = {};
+  rootSeen = false;
+  /** @type {number | undefined} */
+  firstStartMs = undefined;
+  /** @type {number | undefined} */
+  lastEndMs = undefined;
+  /** @type {string | undefined} */
+  rootSpanId = undefined;
+  /** @type {string | undefined} */
+  rootName = undefined;
+  /** @type {MetadataValue | undefined} */
+  rootKind = undefined;
+  /** @type {number | undefined} */
+  rootStartMs = undefined;
+  /** @type {number | undefined} */
+  rootDurationMs = undefined;
+  exceptionEventCount = NONE;
+  exceptionEscapedCount = NONE;
+  /** @type {Set<string>} */
+  exceptionTypes = new Set();
+
+  /**
+   * @param {string} traceId
+   */
+  constructor(traceId) {
+    this.traceId = traceId;
+  }
+
+  /**
+   * @param {ReadonlySpanAttributes} attributes
+   * @param {Readonly<Record<string, unknown>>} span
+   * @returns {void}
+   */
+  record(attributes, span) {
+    this.spanCount += 1;
+    if (attributes.status === "error") {
+      this.errorSpanCount += 1;
+    }
+    this.recordExceptions(attributes.metadata);
+    const startMs = openTelemetryTimeMs(span["startTime"]);
+    this.recordWindow(startMs, endMsFromOpenTelemetryReadableSpan(span, startMs, attributes.durationMs));
+    this.copyMetadata(attributes.metadata, false);
+    const isRootSpan = attributes.parentSpanId === undefined;
+    if (isRootSpan || this.rootSpanId === undefined) {
+      this.recordRoot(attributes, isRootSpan, startMs);
+    }
+  }
+
+  /**
+   * @param {number | undefined} startMs
+   * @param {number | undefined} endMs
+   * @returns {void}
+   */
+  recordWindow(startMs, endMs) {
+    if (startMs !== undefined && (this.firstStartMs === undefined || startMs < this.firstStartMs)) {
+      this.firstStartMs = startMs;
+    }
+    if (endMs !== undefined && (this.lastEndMs === undefined || endMs > this.lastEndMs)) {
+      this.lastEndMs = endMs;
+    }
+  }
+
+  /**
+   * @param {ReadonlySpanAttributes} attributes
+   * @param {boolean} isRootSpan
+   * @param {number | undefined} startMs
+   * @returns {void}
+   */
+  recordRoot(attributes, isRootSpan, startMs) {
+    this.rootSpanId = attributes.spanId;
+    this.rootName = attributes.name;
+    this.rootKind = attributes.metadata?.["otel.kind"];
+    this.rootSeen = isRootSpan;
+    if (startMs !== undefined) {
+      this.rootStartMs = startMs;
+    }
+    if (attributes.durationMs !== undefined) {
+      this.rootDurationMs = attributes.durationMs;
+    }
+    this.copyMetadata(attributes.metadata, true);
+  }
+
+  /**
+   * @param {Readonly<Metadata> | undefined} metadata
+   * @returns {void}
+   */
+  recordExceptions(metadata) {
+    this.exceptionEventCount += positiveSafeInteger(metadata, "otel.exception_event_count");
+    this.exceptionEscapedCount += positiveSafeInteger(metadata, "otel.exception_escaped_count");
+    const types = metadata?.["otel.exception_types"];
+    if (typeof types === "string" && types.trim() !== "") {
+      for (const type of types.split(",")) {
+        const safeType = safeOpenTelemetryExceptionType(type);
+        if (safeType !== undefined) {
+          this.exceptionTypes.add(safeType);
+        }
+      }
+    }
+  }
+
+  /**
+   * @param {Readonly<Metadata> | undefined} metadata
+   * @param {boolean} overwrite
+   * @returns {void}
+   */
+  copyMetadata(metadata, overwrite) {
+    if (metadata === undefined) {
+      return;
+    }
+    for (const [key, value] of Object.entries(metadata)) {
+      if (
+        TRACE_SUMMARY_METADATA_KEYS.has(key)
+        && (overwrite || this.metadata[key] === undefined)
+        && isMetadataValue(value)
+      ) {
+        this.metadata[key] = value;
+      }
+    }
+  }
+
+  /**
+   * @returns {number | undefined}
+   */
+  durationMs() {
+    if (this.firstStartMs !== undefined && this.lastEndMs !== undefined && this.lastEndMs >= this.firstStartMs) {
+      return this.lastEndMs - this.firstStartMs;
+    }
+    return this.rootDurationMs;
+  }
+
+  /**
+   * @param {(() => unknown) | undefined} fallbackTimestamp
+   * @returns {unknown}
+   */
+  timestamp(fallbackTimestamp) {
+    return timestampFromOpenTelemetryTime(this.rootStartMs)
+      ?? timestampFromOpenTelemetryTime(this.firstStartMs)
+      ?? fallbackTimestampValue(fallbackTimestamp);
+  }
+
+  /**
+   * @returns {Metadata}
+   */
+  summaryMetadata() {
+    return compactMetadata({
+      source: "opentelemetry.trace_summary",
+      ...this.metadata,
+      "otel.trace.span_count": this.spanCount,
+      ...(this.errorSpanCount > NONE ? { "otel.trace.error_span_count": this.errorSpanCount } : {}),
+      ...(this.exceptionEventCount > NONE ? { "otel.trace.exception_event_count": this.exceptionEventCount } : {}),
+      ...(this.exceptionEscapedCount > NONE ? { "otel.trace.exception_escaped_count": this.exceptionEscapedCount } : {}),
+      ...(this.exceptionTypes.size > NONE ? { "otel.trace.exception_types": [...this.exceptionTypes].join(",") } : {}),
+      ...(isTruthy(this.rootSpanId) ? { "otel.trace.root_span_id": this.rootSpanId } : {}),
+      ...(isTruthy(this.rootName) ? { "otel.trace.root_name": this.rootName } : {}),
+      ...(isTruthy(this.rootKind) ? { "otel.trace.root_kind": this.rootKind } : {}),
+      "otel.trace.summary_kind": this.rootSeen ? "rooted" : "flush_batch"
+    });
+  }
+
+  /**
+   * @returns {SpanAttributes}
+   */
+  attributes() {
+    const metadata = this.summaryMetadata();
+    const durationMs = this.durationMs();
+    return {
+      name: isTruthy(this.rootName) ? `opentelemetry.trace:${String(this.rootName)}` : "opentelemetry.trace",
+
+      traceId: this.traceId,
+
+      spanId: defaultSpanIdFactory(),
+      status: this.errorSpanCount > NONE ? "error" : "ok",
+      ...(durationMs === undefined ? {} : { durationMs }),
+      ...(Object.keys(metadata).length > NONE ? { metadata } : {})
+    };
+  }
+}
+
+module.exports = { OpenTelemetryTraceSummary };

package/opentelemetry-time.cjs

@@ -0,0 +1,131 @@
+const { isList } = require("./validation.cjs");
+
+/**
+ * @typedef {Readonly<Record<string, unknown>>} ReadableSpan
+ */
+
+const HR_TIME_PARTS = 2;
+const MS_PER_SECOND = 1000;
+const NANOS_PER_MS = 1_000_000;
+const MIN_HR_TIME_PART = 0;
+
+/**
+ * @param {unknown} value
+ * @returns {value is number}
+ */
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function openTelemetryTimeMs(value) {
+  if (isList(value) && value.length >= HR_TIME_PARTS) {
+    const [seconds, nanos] = value;
+    if (isFiniteNumber(seconds) && isFiniteNumber(nanos)) {
+      return seconds * MS_PER_SECOND + nanos / NANOS_PER_MS;
+    }
+  }
+  if (isFiniteNumber(value)) {
+    return value;
+  }
+  if (value instanceof Date && !Number.isNaN(value.valueOf())) {
+    return value.valueOf();
+  }
+  return undefined;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function openTelemetryDurationMs(value) {
+  if (!isList(value) || value.length < HR_TIME_PARTS) {
+    return undefined;
+  }
+  const [seconds, nanos] = value;
+  if (
+    !isFiniteNumber(seconds)
+    || !isFiniteNumber(nanos)
+    || seconds < MIN_HR_TIME_PART
+    || nanos < MIN_HR_TIME_PART
+  ) {
+    return undefined;
+  }
+  return seconds * MS_PER_SECOND + nanos / NANOS_PER_MS;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function timestampFromOpenTelemetryTime(value) {
+  const milliseconds = openTelemetryTimeMs(value);
+  if (milliseconds === undefined) {
+    return undefined;
+  }
+  const date = new Date(milliseconds);
+  return Number.isNaN(date.valueOf()) ? undefined : date.toISOString();
+}
+
+/**
+ * @param {(() => unknown) | undefined} fallbackTimestamp
+ * @returns {unknown}
+ */
+function fallbackTimestampValue(fallbackTimestamp) {
+  return fallbackTimestamp === undefined ? new Date().toISOString() : fallbackTimestamp();
+}
+
+/**
+ * @param {ReadableSpan} span
+ * @returns {number | undefined}
+ */
+function durationMsFromOpenTelemetryReadableSpan(span) {
+  const durationMs = openTelemetryDurationMs(span["duration"]);
+  if (durationMs !== undefined) {
+    return durationMs;
+  }
+  const startMs = openTelemetryTimeMs(span["startTime"]);
+  const endMs = openTelemetryTimeMs(span["endTime"]);
+  if (startMs !== undefined && endMs !== undefined && endMs >= startMs) {
+    return endMs - startMs;
+  }
+  return undefined;
+}
+
+/**
+ * @param {ReadableSpan} span
+ * @param {number | undefined} startMs
+ * @param {number | undefined} durationMs
+ * @returns {number | undefined}
+ */
+function endMsFromOpenTelemetryReadableSpan(span, startMs, durationMs) {
+  const endMs = openTelemetryTimeMs(span["endTime"]);
+  if (endMs !== undefined) {
+    return endMs;
+  }
+  if (startMs !== undefined && durationMs !== undefined) {
+    return startMs + durationMs;
+  }
+  return undefined;
+}
+
+/**
+ * @param {ReadableSpan} span
+ * @param {(() => unknown) | undefined} fallbackTimestamp
+ * @returns {unknown}
+ */
+function timestampFromOpenTelemetryReadableSpan(span, fallbackTimestamp) {
+  return timestampFromOpenTelemetryTime(span["startTime"]) ?? fallbackTimestampValue(fallbackTimestamp);
+}
+
+module.exports = {
+  durationMsFromOpenTelemetryReadableSpan,
+  endMsFromOpenTelemetryReadableSpan,
+  fallbackTimestampValue,
+  openTelemetryTimeMs,
+  timestampFromOpenTelemetryReadableSpan,
+  timestampFromOpenTelemetryTime
+};