@chidchanun/bcp 0.2.16 → 0.2.18

package/packages/client/src/observability.mjs

@@ -0,0 +1,1251 @@
+// packages/server/src/observability.ts
+var DEFAULT_HISTOGRAM_BUCKETS = [
+  5e-3,
+  0.01,
+  0.025,
+  0.05,
+  0.1,
+  0.25,
+  0.5,
+  1,
+  2.5,
+  5,
+  10
+];
+function createMetricsRegistry() {
+  const definitions = /* @__PURE__ */ new Map();
+  return {
+    counter(name, options = {}) {
+      const definition = getOrCreateSimpleDefinition(
+        definitions,
+        "counter",
+        name,
+        options
+      );
+      return {
+        name: definition.name,
+        inc(value = 1, labels = {}) {
+          assertFiniteNumber(
+            value,
+            "counter increment"
+          );
+          if (value < 0) {
+            throw new TypeError(
+              "BCP Observability: counters cannot be decreased."
+            );
+          }
+          const series = getSimpleSeries(
+            definition,
+            labels
+          );
+          series.value += value;
+        }
+      };
+    },
+    gauge(name, options = {}) {
+      const definition = getOrCreateSimpleDefinition(
+        definitions,
+        "gauge",
+        name,
+        options
+      );
+      const read = (labels) => getSimpleSeries(
+        definition,
+        labels
+      );
+      return {
+        name: definition.name,
+        set(value, labels = {}) {
+          assertFiniteNumber(
+            value,
+            "gauge value"
+          );
+          read(labels).value = value;
+        },
+        inc(value = 1, labels = {}) {
+          assertFiniteNumber(
+            value,
+            "gauge increment"
+          );
+          read(labels).value += value;
+        },
+        dec(value = 1, labels = {}) {
+          assertFiniteNumber(
+            value,
+            "gauge decrement"
+          );
+          read(labels).value -= value;
+        }
+      };
+    },
+    histogram(name, options = {}) {
+      const metricName = normalizeMetricName(
+        name
+      );
+      const labelNames = normalizeLabelNames(
+        options.labelNames
+      );
+      const buckets = normalizeBuckets(
+        options.buckets
+      );
+      const existing = definitions.get(
+        metricName
+      );
+      let definition;
+      if (existing) {
+        assertCompatibleDefinition(
+          existing,
+          "histogram",
+          labelNames
+        );
+        if (existing.type !== "histogram" || !sameNumbers(
+          existing.buckets,
+          buckets
+        )) {
+          throw new Error(
+            `BCP Observability: metric ${metricName} was already registered with different histogram buckets.`
+          );
+        }
+        definition = existing;
+      } else {
+        definition = {
+          type: "histogram",
+          name: metricName,
+          help: normalizeHelp(
+            options.help,
+            metricName
+          ),
+          labelNames,
+          buckets,
+          series: /* @__PURE__ */ new Map()
+        };
+        definitions.set(
+          metricName,
+          definition
+        );
+      }
+      return {
+        name: definition.name,
+        observe(value, labels = {}) {
+          assertFiniteNumber(
+            value,
+            "histogram observation"
+          );
+          const normalizedLabels = normalizeLabels(
+            definition.labelNames,
+            labels
+          );
+          const key = serializeLabels(
+            definition.labelNames,
+            normalizedLabels
+          );
+          let series = definition.series.get(
+            key
+          );
+          if (!series) {
+            series = {
+              labels: normalizedLabels,
+              count: 0,
+              sum: 0,
+              buckets: definition.buckets.map(
+                () => 0
+              )
+            };
+            definition.series.set(
+              key,
+              series
+            );
+          }
+          series.count += 1;
+          series.sum += value;
+          for (let index = 0; index < definition.buckets.length; index++) {
+            if (value <= definition.buckets[index]) {
+              series.buckets[index] += 1;
+            }
+          }
+        }
+      };
+    },
+    metrics() {
+      return renderMetrics(
+        definitions
+      );
+    },
+    reset() {
+      for (const definition of definitions.values()) {
+        definition.series.clear();
+      }
+    }
+  };
+}
+function createRequestMetricsMiddleware(registry, options = {}) {
+  const prefix = normalizePrefix(
+    options.prefix
+  );
+  const labelNames = [];
+  if (options.includeMethod !== false) {
+    labelNames.push(
+      "method"
+    );
+  }
+  if (options.includeStatus !== false) {
+    labelNames.push(
+      "status"
+    );
+  }
+  const requests = registry.counter(
+    `${prefix}http_requests_total`,
+    {
+      help: "Total HTTP requests observed by BCP middleware.",
+      labelNames
+    }
+  );
+  const duration = registry.histogram(
+    `${prefix}http_request_duration_seconds`,
+    {
+      help: "HTTP request duration observed by BCP middleware.",
+      labelNames
+    }
+  );
+  return async (request, next) => {
+    const startedAt = process.hrtime.bigint();
+    let status = 500;
+    try {
+      const response = await next();
+      status = response.status;
+      return response;
+    } finally {
+      const elapsed = Number(
+        process.hrtime.bigint() - startedAt
+      ) / 1e9;
+      const labels = {};
+      if (options.includeMethod !== false) {
+        labels.method = request.method.toUpperCase();
+      }
+      if (options.includeStatus !== false) {
+        labels.status = String(status);
+      }
+      requests.inc(
+        1,
+        labels
+      );
+      duration.observe(
+        elapsed,
+        labels
+      );
+    }
+  };
+}
+function createMetricsResponse(registry) {
+  return new Response(
+    registry.metrics(),
+    {
+      status: 200,
+      headers: {
+        "content-type": "text/plain; version=0.0.4; charset=utf-8",
+        "cache-control": "no-store"
+      }
+    }
+  );
+}
+function createHealthRegistry() {
+  const checks = /* @__PURE__ */ new Map();
+  return {
+    register(name, check, options = {}) {
+      const normalizedName = normalizeHealthCheckName(
+        name
+      );
+      const timeoutMs = normalizeHealthTimeout(
+        options.timeoutMs
+      );
+      if (checks.has(
+        normalizedName
+      )) {
+        throw new Error(
+          `BCP Observability: health check ${normalizedName} is already registered.`
+        );
+      }
+      checks.set(
+        normalizedName,
+        {
+          check,
+          timeoutMs
+        }
+      );
+      return () => {
+        checks.delete(
+          normalizedName
+        );
+      };
+    },
+    async run() {
+      const results = await Promise.all(
+        Array.from(
+          checks.entries()
+        ).map(
+          async ([
+            name,
+            definition
+          ]) => runHealthCheck(
+            name,
+            definition.check,
+            definition.timeoutMs
+          )
+        )
+      );
+      const ok = results.every(
+        (item) => item.ok
+      );
+      return {
+        ok,
+        status: ok ? "healthy" : "unhealthy",
+        checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        checks: results
+      };
+    },
+    async response() {
+      const report = await this.run();
+      return Response.json(
+        report,
+        {
+          status: report.ok ? 200 : 503,
+          headers: {
+            "cache-control": "no-store"
+          }
+        }
+      );
+    },
+    clear() {
+      checks.clear();
+    }
+  };
+}
+function getOrCreateSimpleDefinition(definitions, type, name, options) {
+  const metricName = normalizeMetricName(
+    name
+  );
+  const labelNames = normalizeLabelNames(
+    options.labelNames
+  );
+  const existing = definitions.get(
+    metricName
+  );
+  if (existing) {
+    assertCompatibleDefinition(
+      existing,
+      type,
+      labelNames
+    );
+    return existing;
+  }
+  const definition = {
+    type,
+    name: metricName,
+    help: normalizeHelp(
+      options.help,
+      metricName
+    ),
+    labelNames,
+    series: /* @__PURE__ */ new Map()
+  };
+  definitions.set(
+    metricName,
+    definition
+  );
+  return definition;
+}
+function getSimpleSeries(definition, labels) {
+  const normalizedLabels = normalizeLabels(
+    definition.labelNames,
+    labels
+  );
+  const key = serializeLabels(
+    definition.labelNames,
+    normalizedLabels
+  );
+  let series = definition.series.get(
+    key
+  );
+  if (!series) {
+    series = {
+      labels: normalizedLabels,
+      value: 0
+    };
+    definition.series.set(
+      key,
+      series
+    );
+  }
+  return series;
+}
+function renderMetrics(definitions) {
+  const lines = [];
+  for (const definition of Array.from(
+    definitions.values()
+  ).sort(
+    (left, right) => left.name.localeCompare(
+      right.name
+    )
+  )) {
+    lines.push(
+      `# HELP ${definition.name} ${escapeHelp(definition.help)}`,
+      `# TYPE ${definition.name} ${definition.type}`
+    );
+    if (definition.type === "histogram") {
+      for (const series of definition.series.values()) {
+        for (let index = 0; index < definition.buckets.length; index++) {
+          lines.push(
+            `${definition.name}_bucket${renderLabels({
+              ...series.labels,
+              le: String(
+                definition.buckets[index]
+              )
+            })} ${series.buckets[index]}`
+          );
+        }
+        lines.push(
+          `${definition.name}_bucket${renderLabels({
+            ...series.labels,
+            le: "+Inf"
+          })} ${series.count}`,
+          `${definition.name}_sum${renderLabels(series.labels)} ${series.sum}`,
+          `${definition.name}_count${renderLabels(series.labels)} ${series.count}`
+        );
+      }
+    } else {
+      for (const series of definition.series.values()) {
+        lines.push(
+          `${definition.name}${renderLabels(series.labels)} ${series.value}`
+        );
+      }
+    }
+  }
+  return lines.length > 0 ? `${lines.join("\n")}
+` : "";
+}
+async function runHealthCheck(name, check, timeoutMs) {
+  const startedAt = performance.now();
+  try {
+    const result = await withTimeout(
+      Promise.resolve().then(
+        check
+      ),
+      timeoutMs
+    );
+    const normalized = typeof result === "boolean" ? {
+      ok: result
+    } : result;
+    return {
+      name,
+      ok: normalized.ok === true,
+      durationMs: elapsedMilliseconds(
+        startedAt
+      ),
+      ...normalized.detail ? {
+        detail: normalized.detail
+      } : {}
+    };
+  } catch (error) {
+    return {
+      name,
+      ok: false,
+      durationMs: elapsedMilliseconds(
+        startedAt
+      ),
+      detail: error instanceof Error ? error.message : "Health check failed."
+    };
+  }
+}
+function withTimeout(promise, timeoutMs) {
+  return new Promise(
+    (resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(
+          new Error(
+            `Health check timed out after ${timeoutMs}ms.`
+          )
+        ),
+        timeoutMs
+      );
+      timeout.unref?.();
+      promise.then(
+        (value) => {
+          clearTimeout(
+            timeout
+          );
+          resolve(value);
+        },
+        (error) => {
+          clearTimeout(
+            timeout
+          );
+          reject(error);
+        }
+      );
+    }
+  );
+}
+function normalizeMetricName(value) {
+  const name = value.trim();
+  if (!/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(
+    name
+  )) {
+    throw new TypeError(
+      `BCP Observability: invalid metric name "${value}".`
+    );
+  }
+  return name;
+}
+function normalizeLabelNames(values) {
+  const names = Array.from(
+    new Set(
+      (values ?? []).map(
+        (value) => value.trim()
+      )
+    )
+  );
+  for (const name of names) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(
+      name
+    ) || name === "le") {
+      throw new TypeError(
+        `BCP Observability: invalid metric label name "${name}".`
+      );
+    }
+  }
+  return names;
+}
+function normalizeLabels(labelNames, labels) {
+  const received = Object.keys(
+    labels
+  ).sort();
+  const expected = [
+    ...labelNames
+  ].sort();
+  if (received.length !== expected.length || received.some(
+    (name, index) => name !== expected[index]
+  )) {
+    throw new TypeError(
+      `BCP Observability: metric labels must match [${labelNames.join(", ")}].`
+    );
+  }
+  return Object.fromEntries(
+    labelNames.map(
+      (name) => [
+        name,
+        String(
+          labels[name]
+        )
+      ]
+    )
+  );
+}
+function serializeLabels(labelNames, labels) {
+  return labelNames.map(
+    (name) => `${name}=${labels[name]}`
+  ).join("\0");
+}
+function renderLabels(labels) {
+  const entries = Object.entries(
+    labels
+  );
+  if (entries.length === 0) {
+    return "";
+  }
+  return `{${entries.map(
+    ([
+      name,
+      value
+    ]) => `${name}="${escapeLabelValue(value)}"`
+  ).join(",")}}`;
+}
+function normalizeBuckets(values) {
+  const buckets = [
+    ...values ?? DEFAULT_HISTOGRAM_BUCKETS
+  ].sort(
+    (left, right) => left - right
+  );
+  if (buckets.length === 0 || buckets.some(
+    (value) => !Number.isFinite(
+      value
+    )
+  )) {
+    throw new TypeError(
+      "BCP Observability: histogram buckets must contain finite numbers."
+    );
+  }
+  return Array.from(
+    new Set(
+      buckets
+    )
+  );
+}
+function assertCompatibleDefinition(existing, expectedType, labelNames) {
+  if (existing.type !== expectedType || !sameStrings(
+    existing.labelNames,
+    labelNames
+  )) {
+    throw new Error(
+      `BCP Observability: metric ${existing.name} was already registered with a different definition.`
+    );
+  }
+}
+function normalizeHelp(value, fallback) {
+  return value?.trim() || fallback;
+}
+function normalizePrefix(value) {
+  if (!value) {
+    return "bcp_";
+  }
+  const prefix = value.trim();
+  if (!/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(
+    prefix
+  )) {
+    throw new TypeError(
+      "BCP Observability: metrics prefix is invalid."
+    );
+  }
+  return prefix.endsWith("_") ? prefix : `${prefix}_`;
+}
+function normalizeHealthCheckName(value) {
+  const name = value.trim();
+  if (!name) {
+    throw new TypeError(
+      "BCP Observability: health check name must not be empty."
+    );
+  }
+  return name;
+}
+function normalizeHealthTimeout(value) {
+  const timeoutMs = value ?? 5e3;
+  if (!Number.isFinite(
+    timeoutMs
+  ) || timeoutMs <= 0) {
+    throw new TypeError(
+      "BCP Observability: health check timeout must be a positive finite number of milliseconds."
+    );
+  }
+  return Math.floor(
+    timeoutMs
+  );
+}
+function assertFiniteNumber(value, label) {
+  if (!Number.isFinite(
+    value
+  )) {
+    throw new TypeError(
+      `BCP Observability: ${label} must be a finite number.`
+    );
+  }
+}
+function sameStrings(left, right) {
+  return left.length === right.length && left.every(
+    (value, index) => value === right[index]
+  );
+}
+function sameNumbers(left, right) {
+  return left.length === right.length && left.every(
+    (value, index) => value === right[index]
+  );
+}
+function escapeHelp(value) {
+  return value.replaceAll(
+    "\\",
+    "\\\\"
+  ).replaceAll(
+    "\n",
+    "\\n"
+  );
+}
+function escapeLabelValue(value) {
+  return value.replaceAll(
+    "\\",
+    "\\\\"
+  ).replaceAll(
+    '"',
+    '\\"'
+  ).replaceAll(
+    "\n",
+    "\\n"
+  );
+}
+function elapsedMilliseconds(startedAt) {
+  return Math.round(
+    (performance.now() - startedAt) * 1e3
+  ) / 1e3;
+}
+
+// packages/server/src/observability-v3.ts
+import {
+  AsyncLocalStorage
+} from "node:async_hooks";
+import {
+  randomBytes,
+  randomUUID
+} from "node:crypto";
+var TRACEPARENT_PATTERN = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+var traceStorage = new AsyncLocalStorage();
+function createTracer(options = {}) {
+  const exporter = options.exporter;
+  const now = options.now ?? Date.now;
+  const idFactory = options.idFactory ?? createDefaultTraceIdFactory();
+  const serviceName = normalizeOptionalText(options.serviceName);
+  const defaultAttributes = normalizeAttributes(options.defaultAttributes);
+  function startSpan(rawName, spanOptions = {}) {
+    const name = normalizeName(rawName, "span name");
+    const parent = spanOptions.parent === void 0 ? currentTraceContext() : spanOptions.parent ?? void 0;
+    const traceId = parent?.traceId ?? normalizeTraceId(idFactory.traceId());
+    const spanId = normalizeSpanId(idFactory.spanId());
+    const traceFlags = parent?.traceFlags ?? "01";
+    const correlationId = parent?.correlationId ?? normalizeCorrelationId(idFactory.correlationId());
+    const tracestate = parent?.tracestate;
+    const context = {
+      traceId,
+      spanId,
+      traceFlags,
+      correlationId,
+      ...tracestate ? { tracestate } : {}
+    };
+    const attributes = {
+      ...defaultAttributes,
+      ...normalizeAttributes(spanOptions.attributes)
+    };
+    const events = [];
+    const startedAt = spanOptions.startTime ?? now();
+    assertTimestamp(startedAt, "span startTime");
+    const kind = spanOptions.kind ?? "internal";
+    let status = "unset";
+    let statusMessage;
+    let ended = false;
+    let completed;
+    const span = {
+      name,
+      context,
+      parentSpanId: parent?.spanId,
+      kind,
+      get status() {
+        return status;
+      },
+      get ended() {
+        return ended;
+      },
+      setAttribute(rawAttributeName, value) {
+        assertNotEnded();
+        attributes[normalizeName(rawAttributeName, "attribute name")] = normalizeAttributeValue(value);
+      },
+      addEvent(rawEventName, eventAttributes = {}) {
+        assertNotEnded();
+        const timestamp = now();
+        assertTimestamp(timestamp, "event timestamp");
+        events.push({
+          name: normalizeName(rawEventName, "event name"),
+          timestamp,
+          attributes: normalizeAttributes(eventAttributes)
+        });
+      },
+      setStatus(nextStatus, message) {
+        assertNotEnded();
+        status = normalizeStatus(nextStatus);
+        statusMessage = normalizeOptionalText(message);
+      },
+      async end(endTime) {
+        if (completed) {
+          return cloneTraceSpanRecord(completed);
+        }
+        const endedAt = endTime ?? now();
+        assertTimestamp(endedAt, "span endTime");
+        if (endedAt < startedAt) {
+          throw new RangeError(
+            "BCP Observability: span endTime cannot be earlier than startTime."
+          );
+        }
+        ended = true;
+        completed = {
+          name,
+          kind,
+          traceId,
+          spanId,
+          ...parent?.spanId ? { parentSpanId: parent.spanId } : {},
+          traceFlags,
+          correlationId,
+          ...tracestate ? { tracestate } : {},
+          ...serviceName ? { serviceName } : {},
+          startedAt,
+          endedAt,
+          durationMs: endedAt - startedAt,
+          status,
+          ...statusMessage ? { statusMessage } : {},
+          attributes: { ...attributes },
+          events: events.map(cloneTraceEvent)
+        };
+        try {
+          await exporter?.export(
+            cloneTraceSpanRecord(completed)
+          );
+        } catch {
+        }
+        return cloneTraceSpanRecord(completed);
+      }
+    };
+    return span;
+    function assertNotEnded() {
+      if (ended) {
+        throw new Error(
+          `BCP Observability: span "${name}" has already ended.`
+        );
+      }
+    }
+  }
+  async function withSpan(name, callback, spanOptions = {}) {
+    if (typeof callback !== "function") {
+      throw new TypeError(
+        "BCP Observability: span callback must be a function."
+      );
+    }
+    const span = startSpan(name, spanOptions);
+    return await traceStorage.run(
+      span.context,
+      async () => {
+        try {
+          const value = await callback(span);
+          if (!span.ended && span.status === "unset") {
+            span.setStatus("ok");
+          }
+          return value;
+        } catch (error) {
+          if (!span.ended) {
+            span.setStatus(
+              "error",
+              error instanceof Error ? error.message : "Span callback failed."
+            );
+            span.addEvent("exception", {
+              "exception.type": error instanceof Error ? error.name : typeof error,
+              "exception.message": error instanceof Error ? error.message : String(error)
+            });
+          }
+          throw error;
+        } finally {
+          if (!span.ended) {
+            await span.end();
+          }
+        }
+      }
+    );
+  }
+  const tracer = {
+    startSpan,
+    withSpan,
+    currentContext() {
+      return currentTraceContext();
+    },
+    runWithContext(context, callback) {
+      return runWithTraceContext(context, callback);
+    },
+    async shutdown() {
+      await exporter?.shutdown?.();
+    }
+  };
+  return tracer;
+}
+function currentTraceContext() {
+  const current = traceStorage.getStore();
+  return current ? cloneTraceContext(current) : void 0;
+}
+function runWithTraceContext(context, callback) {
+  if (typeof callback !== "function") {
+    throw new TypeError(
+      "BCP Observability: trace context callback must be a function."
+    );
+  }
+  return traceStorage.run(
+    normalizeTraceContext(context),
+    callback
+  );
+}
+function createTraceCarrier(context = currentTraceContext()) {
+  if (!context) {
+    return void 0;
+  }
+  const normalized = normalizeTraceContext(context);
+  return {
+    traceparent: formatTraceparent(normalized),
+    correlationId: normalized.correlationId,
+    ...normalized.tracestate ? { tracestate: normalized.tracestate } : {}
+  };
+}
+function runWithTraceCarrier(carrier, callback) {
+  if (!carrier) {
+    return callback();
+  }
+  const context = extractTraceCarrier(carrier);
+  return context ? runWithTraceContext(context, callback) : callback();
+}
+function extractTraceCarrier(carrier) {
+  const traceparent = carrier.traceparent;
+  if (!traceparent) {
+    return null;
+  }
+  const parsed = parseTraceparent(traceparent);
+  if (!parsed) {
+    return null;
+  }
+  const correlationId = typeof carrier.correlationId === "string" ? carrier.correlationId : parsed.traceId;
+  const tracestate = typeof carrier.tracestate === "string" ? normalizeOptionalText(carrier.tracestate) : void 0;
+  return {
+    ...parsed,
+    correlationId: normalizeCorrelationId(correlationId),
+    ...tracestate ? { tracestate } : {}
+  };
+}
+function injectTraceHeaders(headers, context = currentTraceContext()) {
+  if (!(headers instanceof Headers)) {
+    throw new TypeError(
+      "BCP Observability: injectTraceHeaders() requires Headers."
+    );
+  }
+  if (!context) {
+    return headers;
+  }
+  const normalized = normalizeTraceContext(context);
+  headers.set("traceparent", formatTraceparent(normalized));
+  headers.set("x-correlation-id", normalized.correlationId);
+  if (normalized.tracestate) {
+    headers.set("tracestate", normalized.tracestate);
+  } else {
+    headers.delete("tracestate");
+  }
+  return headers;
+}
+function extractTraceHeaders(input) {
+  const headers = input instanceof Headers ? input : input.headers;
+  if (!(headers instanceof Headers)) {
+    throw new TypeError(
+      "BCP Observability: extractTraceHeaders() requires Headers or a request-like object."
+    );
+  }
+  const parsed = parseTraceparent(headers.get("traceparent"));
+  if (!parsed) {
+    return null;
+  }
+  const correlationId = headers.get("x-correlation-id") ?? parsed.traceId;
+  const tracestate = normalizeOptionalText(
+    headers.get("tracestate") ?? void 0
+  );
+  return {
+    ...parsed,
+    correlationId: normalizeCorrelationId(correlationId),
+    ...tracestate ? { tracestate } : {}
+  };
+}
+function formatTraceparent(context) {
+  return [
+    "00",
+    normalizeTraceId(context.traceId),
+    normalizeSpanId(context.spanId),
+    normalizeTraceFlags(context.traceFlags)
+  ].join("-");
+}
+function parseTraceparent(value) {
+  if (!value) {
+    return null;
+  }
+  const match = TRACEPARENT_PATTERN.exec(
+    value.trim().toLowerCase()
+  );
+  if (!match || /^0+$/.test(match[1]) || /^0+$/.test(match[2])) {
+    return null;
+  }
+  return {
+    traceId: match[1],
+    spanId: match[2],
+    traceFlags: match[3]
+  };
+}
+function createRequestTracingMiddleware(tracer, options = {}) {
+  if (!tracer) {
+    throw new TypeError(
+      "BCP Observability: request tracing requires a tracer."
+    );
+  }
+  const middleware = async (request, next, _context) => {
+    const incoming = extractTraceHeaders(request.headers);
+    const spanName = typeof options.spanName === "function" ? options.spanName(request) : options.spanName ?? `HTTP ${request.method.toUpperCase()}`;
+    const optionAttributes = typeof options.attributes === "function" ? options.attributes(request) : options.attributes ?? {};
+    return tracer.withSpan(
+      spanName,
+      async (span) => {
+        span.setAttribute(
+          "http.request.method",
+          request.method.toUpperCase()
+        );
+        span.setAttribute(
+          "url.path",
+          request.nextUrl.pathname
+        );
+        let response;
+        try {
+          response = await next();
+          span.setAttribute(
+            "http.response.status_code",
+            response.status
+          );
+          if (response.status >= 500) {
+            span.setStatus("error", `HTTP ${response.status}`);
+          }
+        } catch (error) {
+          span.setStatus(
+            "error",
+            error instanceof Error ? error.message : "HTTP request failed."
+          );
+          throw error;
+        }
+        return options.includeResponseHeaders === false ? response : cloneResponseWithTraceHeaders(
+          response,
+          span.context
+        );
+      },
+      {
+        parent: incoming,
+        kind: "server",
+        attributes: optionAttributes
+      }
+    );
+  };
+  return middleware;
+}
+function createMemoryTraceSpanExporter() {
+  const records = [];
+  return {
+    export(span) {
+      records.push(cloneTraceSpanRecord(span));
+    },
+    spans() {
+      return records.map(cloneTraceSpanRecord);
+    },
+    clear() {
+      records.length = 0;
+    }
+  };
+}
+function createTraceMetricsExporter(registry, options = {}) {
+  const prefix = normalizeMetricPrefix(
+    options.prefix ?? "bcp_trace"
+  );
+  const labelNames = [
+    "kind",
+    "status",
+    ...options.includeSpanName ? ["span"] : []
+  ];
+  const spans = registry.counter(
+    `${prefix}_spans_total`,
+    {
+      help: "Completed BCP trace spans.",
+      labelNames
+    }
+  );
+  const duration = registry.histogram(
+    `${prefix}_span_duration_seconds`,
+    {
+      help: "BCP trace span duration in seconds.",
+      labelNames
+    }
+  );
+  return {
+    export(span) {
+      const labels = {
+        kind: span.kind,
+        status: span.status
+      };
+      if (options.includeSpanName) {
+        labels.span = span.name;
+      }
+      spans.inc(1, labels);
+      duration.observe(span.durationMs / 1e3, labels);
+    }
+  };
+}
+function createCompositeTraceSpanExporter(exporters) {
+  const list = [...exporters];
+  return {
+    async export(span) {
+      for (const exporter of list) {
+        await exporter.export(cloneTraceSpanRecord(span));
+      }
+    },
+    async shutdown() {
+      for (const exporter of [...list].reverse()) {
+        await exporter.shutdown?.();
+      }
+    }
+  };
+}
+function getTraceLogFields(context = currentTraceContext()) {
+  if (!context) {
+    return {};
+  }
+  const normalized = normalizeTraceContext(context);
+  return {
+    traceId: normalized.traceId,
+    spanId: normalized.spanId,
+    correlationId: normalized.correlationId
+  };
+}
+function createDefaultTraceIdFactory() {
+  return {
+    traceId() {
+      return randomBytes(16).toString("hex");
+    },
+    spanId() {
+      return randomBytes(8).toString("hex");
+    },
+    correlationId() {
+      return randomUUID();
+    }
+  };
+}
+function cloneResponseWithTraceHeaders(response, context) {
+  const headers = new Headers(response.headers);
+  injectTraceHeaders(headers, context);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+function normalizeTraceContext(context) {
+  const tracestate = normalizeOptionalText(context.tracestate);
+  return {
+    traceId: normalizeTraceId(context.traceId),
+    spanId: normalizeSpanId(context.spanId),
+    traceFlags: normalizeTraceFlags(context.traceFlags),
+    correlationId: normalizeCorrelationId(context.correlationId),
+    ...tracestate ? { tracestate } : {}
+  };
+}
+function cloneTraceContext(context) {
+  return { ...context };
+}
+function cloneTraceSpanRecord(span) {
+  return {
+    ...span,
+    attributes: { ...span.attributes },
+    events: span.events.map(cloneTraceEvent)
+  };
+}
+function cloneTraceEvent(event) {
+  return {
+    ...event,
+    attributes: { ...event.attributes }
+  };
+}
+function normalizeAttributes(attributes) {
+  const normalized = {};
+  for (const [rawName, value] of Object.entries(attributes ?? {})) {
+    normalized[normalizeName(rawName, "attribute name")] = normalizeAttributeValue(value);
+  }
+  return normalized;
+}
+function normalizeAttributeValue(value) {
+  if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean") {
+    throw new TypeError(
+      "BCP Observability: trace attributes must be string, number or boolean values."
+    );
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new TypeError(
+      "BCP Observability: numeric trace attributes must be finite."
+    );
+  }
+  return value;
+}
+function normalizeStatus(status) {
+  if (status !== "unset" && status !== "ok" && status !== "error") {
+    throw new TypeError(
+      "BCP Observability: invalid span status."
+    );
+  }
+  return status;
+}
+function normalizeTraceId(value) {
+  const normalized = value.trim().toLowerCase();
+  if (!/^[0-9a-f]{32}$/.test(normalized) || /^0+$/.test(normalized)) {
+    throw new TypeError(
+      "BCP Observability: traceId must be 32 non-zero hexadecimal characters."
+    );
+  }
+  return normalized;
+}
+function normalizeSpanId(value) {
+  const normalized = value.trim().toLowerCase();
+  if (!/^[0-9a-f]{16}$/.test(normalized) || /^0+$/.test(normalized)) {
+    throw new TypeError(
+      "BCP Observability: spanId must be 16 non-zero hexadecimal characters."
+    );
+  }
+  return normalized;
+}
+function normalizeTraceFlags(value) {
+  const normalized = value.trim().toLowerCase();
+  if (!/^[0-9a-f]{2}$/.test(normalized)) {
+    throw new TypeError(
+      "BCP Observability: traceFlags must be two hexadecimal characters."
+    );
+  }
+  return normalized;
+}
+function normalizeCorrelationId(value) {
+  return normalizeName(value, "correlationId");
+}
+function normalizeName(value, field) {
+  const normalized = String(value ?? "").trim();
+  if (!normalized) {
+    throw new TypeError(
+      `BCP Observability: ${field} must be a non-empty string.`
+    );
+  }
+  return normalized;
+}
+function normalizeOptionalText(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const normalized = value.trim();
+  return normalized || void 0;
+}
+function assertTimestamp(value, field) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(
+      `BCP Observability: ${field} must be a finite number.`
+    );
+  }
+}
+function normalizeMetricPrefix(value) {
+  const normalized = value.trim();
+  if (!/^[a-zA-Z_:][a-zA-Z0-9_:]*$/.test(normalized)) {
+    throw new TypeError(
+      "BCP Observability: trace metrics prefix contains unsupported characters."
+    );
+  }
+  return normalized;
+}
+export {
+  createCompositeTraceSpanExporter,
+  createHealthRegistry,
+  createMemoryTraceSpanExporter,
+  createMetricsRegistry,
+  createMetricsResponse,
+  createRequestMetricsMiddleware,
+  createRequestTracingMiddleware,
+  createTraceCarrier,
+  createTraceMetricsExporter,
+  createTracer,
+  currentTraceContext,
+  extractTraceCarrier,
+  extractTraceHeaders,
+  formatTraceparent,
+  getTraceLogFields,
+  injectTraceHeaders,
+  parseTraceparent,
+  runWithTraceCarrier,
+  runWithTraceContext
+};