@logbrew/sdk 0.1.38 → 0.1.39

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

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