@logbrew/sdk 0.1.37 → 0.1.39

package/opentelemetry-keys.cjs

@@ -0,0 +1,183 @@
+const { compactMetadata, isMetadataValue } = require("./log-context.cjs");
+const { SdkError } = require("./sdk-error.cjs");
+const { isList, isRecord, requireNonEmpty } = require("./validation.cjs");
+
+/**
+ * @import { Metadata } from "./index.cjs"
+ * @typedef {Readonly<ReadonlySet<string>>} KeySet
+ * @typedef {Readonly<{
+ *   attributeKeys?: unknown,
+ *   captureUnsampled?: unknown,
+ *   eventAttributeKeys?: unknown,
+ *   includeSpanEvents?: unknown,
+ *   includeSpanLinks?: unknown,
+ *   linkAttributeKeys?: unknown,
+ *   metadata?: unknown,
+ *   resourceAttributeKeys?: unknown
+ * }>} ReadableSpanOptions
+ * @typedef {Readonly<{
+ *   attributeKeys: KeySet,
+ *   captureUnsampled: boolean,
+ *   eventAttributeKeys: KeySet,
+ *   includeSpanEvents: boolean,
+ *   includeSpanLinks: boolean,
+ *   linkAttributeKeys: KeySet,
+ *   metadata: Readonly<Metadata>,
+ *   resourceAttributeKeys: KeySet
+ * }>} ResolvedSpanOptions
+ */
+
+const SPAN_ATTRIBUTE_KEYS = [
+  "db.operation.name",
+  "db.system",
+  "faas.trigger",
+  "graphql.operation.name",
+  "graphql.operation.type",
+  "http.method",
+  "http.request.method",
+  "http.response.status_code",
+  "http.route",
+  "http.status_code",
+  "messaging.operation.name",
+  "messaging.system",
+  "rpc.method",
+  "rpc.service",
+  "rpc.system"
+];
+const RESOURCE_ATTRIBUTE_KEYS = [
+  "deployment.environment",
+  "deployment.environment.name",
+  "service.name",
+  "service.version",
+  "telemetry.sdk.language",
+  "telemetry.sdk.name",
+  "telemetry.sdk.version"
+];
+/** @type {KeySet} */
+const DEFAULT_SPAN_ATTRIBUTE_KEYS = new Set(SPAN_ATTRIBUTE_KEYS);
+/** @type {KeySet} */
+const DEFAULT_RESOURCE_ATTRIBUTE_KEYS = new Set(RESOURCE_ATTRIBUTE_KEYS);
+/** @type {KeySet} */
+const DEFAULT_EVENT_ATTRIBUTE_KEYS = new Set(["exception.escaped", "exception.type"]);
+/** @type {KeySet} */
+const DEFAULT_LINK_ATTRIBUTE_KEYS = new Set();
+/** @type {KeySet} */
+const TRACE_SUMMARY_METADATA_KEYS = new Set([...RESOURCE_ATTRIBUTE_KEYS, ...SPAN_ATTRIBUTE_KEYS]);
+/** @type {KeySet} */
+const SENSITIVE_OTEL_ATTRIBUTE_KEYS = new Set([
+  "code.stacktrace",
+  "db.statement",
+  "exception.message",
+  "exception.stacktrace",
+  "http.request.body",
+  "http.response.body",
+  "http.url",
+  "url.full"
+]);
+const SENSITIVE_OTEL_ATTRIBUTE_PREFIXES = ["http.request.header.", "http.response.header."];
+const SENSITIVE_OTEL_ATTRIBUTE_PATTERN = /(?:^|[._-])(?:authorization|body|cookie|credential|fragment|header|headers|payload|password|passwd|private[-_]?key|query|secret|stack|stacktrace|token)(?:[._-]|$)/iu;
+
+/**
+ * @param {string} key
+ * @returns {boolean}
+ */
+function isSensitiveOpenTelemetryAttributeKey(key) {
+  if (SENSITIVE_OTEL_ATTRIBUTE_KEYS.has(key)) {
+    return true;
+  }
+  if (SENSITIVE_OTEL_ATTRIBUTE_PREFIXES.some((prefix) => key.startsWith(prefix))) {
+    return true;
+  }
+  return SENSITIVE_OTEL_ATTRIBUTE_PATTERN.test(key);
+}
+
+/**
+ * @param {string} label
+ * @param {unknown} extraKey
+ * @returns {string}
+ */
+function allowedExtraKey(label, extraKey) {
+  const key = requireNonEmpty(label, extraKey);
+  if (isSensitiveOpenTelemetryAttributeKey(key)) {
+    throw new SdkError("validation_error", `${label} cannot include sensitive key: ${key}`);
+  }
+  return key;
+}
+
+/**
+ * @param {KeySet} defaultKeys
+ * @param {unknown} extraKeys
+ * @param {string} label
+ * @returns {KeySet}
+ */
+function openTelemetryAttributeKeySet(defaultKeys, extraKeys, label) {
+  const allowedKeys = new Set(defaultKeys);
+  if (extraKeys === undefined) {
+    return allowedKeys;
+  }
+  if (!isList(extraKeys)) {
+    throw new SdkError("validation_error", `${label} must be an array`);
+  }
+  for (const extraKey of extraKeys) {
+    allowedKeys.add(allowedExtraKey(label, extraKey));
+  }
+  return allowedKeys;
+}
+
+/**
+ * @param {ReadableSpanOptions} [options]
+ * @returns {ResolvedSpanOptions}
+ */
+function resolveOpenTelemetryReadableSpanOptions(options = {}) {
+  return {
+    attributeKeys: openTelemetryAttributeKeySet(
+      DEFAULT_SPAN_ATTRIBUTE_KEYS,
+      options.attributeKeys,
+      "OpenTelemetry attributeKeys"
+    ),
+    captureUnsampled: options.captureUnsampled === true,
+    eventAttributeKeys: openTelemetryAttributeKeySet(
+      DEFAULT_EVENT_ATTRIBUTE_KEYS,
+      options.eventAttributeKeys,
+      "OpenTelemetry eventAttributeKeys"
+    ),
+    includeSpanEvents: options.includeSpanEvents !== false,
+    includeSpanLinks: options.includeSpanLinks !== false,
+    linkAttributeKeys: openTelemetryAttributeKeySet(
+      DEFAULT_LINK_ATTRIBUTE_KEYS,
+      options.linkAttributeKeys,
+      "OpenTelemetry linkAttributeKeys"
+    ),
+    metadata: compactMetadata(options.metadata),
+    resourceAttributeKeys: openTelemetryAttributeKeySet(
+      DEFAULT_RESOURCE_ATTRIBUTE_KEYS,
+      options.resourceAttributeKeys,
+      "OpenTelemetry resourceAttributeKeys"
+    )
+  };
+}
+
+/**
+ * @param {unknown} attributes
+ * @param {KeySet} allowedKeys
+ * @returns {Metadata}
+ */
+function openTelemetrySelectedMetadata(attributes, allowedKeys) {
+  /** @type {Metadata} */
+  const metadata = {};
+  if (!isRecord(attributes)) {
+    return metadata;
+  }
+  for (const [key, value] of Object.entries(attributes)) {
+    if (allowedKeys.has(key) && !isSensitiveOpenTelemetryAttributeKey(key) && isMetadataValue(value)) {
+      metadata[key] = value;
+    }
+  }
+  return metadata;
+}
+
+module.exports = {
+  TRACE_SUMMARY_METADATA_KEYS,
+  openTelemetrySelectedMetadata,
+  resolveOpenTelemetryReadableSpanOptions
+};

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