@xylabs/telemetry 5.0.83 → 5.0.84

package/README.md

@@ -46,20 +46,28 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 function cloneContextWithoutSpan(activeCtx, configKeys?): Context;
 ```
 
+Creates a new OpenTelemetry context that preserves baggage and custom keys but has no active span.
+
 ## Parameters
 
 ### activeCtx
 
 `Context`
 
+The context to clone from.
+
 ### configKeys?
 
 `symbol`[] = `[]`
 
+Additional context keys to copy.
+
 ## Returns
 
 `Context`
 
+A new context with baggage but no parent span.
+
   ### <a id="span"></a>span
 
 [**@xylabs/telemetry**](#../README)
@@ -73,6 +81,8 @@ function span<T>(
    tracer?): T;
 ```
 
+Executes a synchronous function within an OpenTelemetry span, recording status and exceptions.
+
 ## Type Parameters
 
 ### T
@@ -85,18 +95,26 @@ function span<T>(
 
 `string`
 
+The span name.
+
 ### fn
 
 () => `T`
 
+The function to execute.
+
 ### tracer?
 
 `Tracer`
 
+Optional tracer to use.
+
 ## Returns
 
 `T`
 
+The return value of `fn`.
+
   ### <a id="spanAsync"></a>spanAsync
 
 [**@xylabs/telemetry**](#../README)
@@ -107,9 +125,11 @@ function span<T>(
 function spanAsync<T>(
    name, 
    fn, 
-__namedParameters?): Promise<T>;
+config?): Promise<T>;
 ```
 
+Executes an async function within an OpenTelemetry span, with optional time budget monitoring.
+
 ## Type Parameters
 
 ### T
@@ -122,18 +142,26 @@ __namedParameters?): Promise<T>;
 
 `string`
 
+The span name.
+
 ### fn
 
 () => `Promise`\<`T`\>
 
-### \_\_namedParameters?
+The async function to execute.
+
+### config?
 
 [`SpanConfig`](#../interfaces/SpanConfig) = `{}`
 
+Optional span configuration (tracer, logger, time budget).
+
 ## Returns
 
 `Promise`\<`T`\>
 
+The resolved value of `fn`.
+
   ### <a id="spanRoot"></a>spanRoot
 
 [**@xylabs/telemetry**](#../README)
@@ -147,6 +175,8 @@ function spanRoot<T>(
    tracer?): T;
 ```
 
+Executes a synchronous function within a new root span that has no parent, even if a span is already active.
+
 ## Type Parameters
 
 ### T
@@ -159,18 +189,26 @@ function spanRoot<T>(
 
 `string`
 
+The span name.
+
 ### fn
 
 () => `T`
 
+The function to execute.
+
 ### tracer?
 
 `Tracer`
 
+Optional tracer to use.
+
 ## Returns
 
 `T`
 
+The return value of `fn`.
+
   ### <a id="spanRootAsync"></a>spanRootAsync
 
 [**@xylabs/telemetry**](#../README)
@@ -181,9 +219,11 @@ function spanRoot<T>(
 function spanRootAsync<T>(
    name, 
    fn, 
-__namedParameters?): Promise<T>;
+config?): Promise<T>;
 ```
 
+Executes an async function within a new root span (no parent), with optional time budget monitoring.
+
 ## Type Parameters
 
 ### T
@@ -196,18 +236,26 @@ __namedParameters?): Promise<T>;
 
 `string`
 
+The span name.
+
 ### fn
 
 () => `Promise`\<`T`\>
 
-### \_\_namedParameters?
+The async function to execute.
+
+### config?
 
 [`SpanConfig`](#../interfaces/SpanConfig) = `{}`
 
+Optional span configuration (tracer, logger, time budget).
+
 ## Returns
 
 `Promise`\<`T`\>
 
+The resolved value of `fn`.
+
   ### <a id="timeBudget"></a>timeBudget
 
 [**@xylabs/telemetry**](#../README)
@@ -223,6 +271,8 @@ function timeBudget<TResult>(
 status?): Promise<TResult>;
 ```
 
+Executes an async function and logs a warning if it exceeds the given time budget.
+
 ## Type Parameters
 
 ### TResult
@@ -235,26 +285,38 @@ status?): Promise<TResult>;
 
 `string`
 
+A label for the function, used in warning messages.
+
 ### logger
 
+The logger to use for budget-exceeded warnings.
+
 `Logger` | `undefined`
 
 ### func
 
 () => `Promise`\<`TResult`\>
 
+The async function to execute.
+
 ### budget
 
 `number`
 
+The time budget in milliseconds.
+
 ### status?
 
 `boolean` = `false`
 
+If true, logs periodic warnings while the function is still running.
+
 ## Returns
 
 `Promise`\<`TResult`\>
 
+The result of the executed function.
+
 ### interfaces
 
   ### <a id="SpanConfig"></a>SpanConfig
@@ -263,6 +325,8 @@ status?): Promise<TResult>;
 
 ***
 
+Configuration options for span creation and execution.
+
 ## Properties
 
 ### logger?
@@ -271,6 +335,8 @@ status?): Promise<TResult>;
 optional logger: Logger | null;
 ```
 
+Optional logger for time budget warnings. Falls back to console if not provided.
+
 ***
 
 ### timeBudgetLimit?
@@ -279,6 +345,8 @@ optional logger: Logger | null;
 optional timeBudgetLimit: number;
 ```
 
+Maximum allowed execution time in milliseconds before logging a warning.
+
 ***
 
 ### tracer?
@@ -287,6 +355,8 @@ optional timeBudgetLimit: number;
 optional tracer: Tracer;
 ```
 
+OpenTelemetry tracer to use. Defaults to a tracer named after the span.
+
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
 

package/dist/neutral/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/span.ts","../../src/timeBudget.ts"],"sourcesContent":["import type {\n  Context,\n  Tracer,\n} from '@opentelemetry/api'\nimport {\n  context, propagation, ROOT_CONTEXT, SpanStatusCode, trace as TRACE_API,\n} from '@opentelemetry/api'\nimport type { Logger } from '@xylabs/logger'\nimport { isDefined } from '@xylabs/typeof'\n\nimport { timeBudget } from './timeBudget.ts'\n\nexport interface SpanConfig {\n  logger?: Logger | null\n  timeBudgetLimit?: number\n  tracer?: Tracer\n}\n\nexport function cloneContextWithoutSpan(activeCtx: Context, configKeys: symbol[] = []): Context {\n  // Start from root to ensure no span is propagated\n  let newCtx = ROOT_CONTEXT\n\n  // Copy baggage\n  const baggage = propagation.getBaggage(activeCtx)\n  if (baggage) {\n    newCtx = propagation.setBaggage(newCtx, baggage)\n  }\n\n  // Copy custom config keys\n  for (const key of configKeys) {\n    const value = activeCtx.getValue(key)\n    if (value !== undefined) {\n      newCtx = newCtx.setValue(key, value)\n    }\n  }\n\n  return newCtx\n}\n\nexport function span<T>(name: string, fn: () => T, tracer?: Tracer): T {\n  const activeTracer = tracer ?? TRACE_API.getTracer(name)\n  if (isDefined(activeTracer)) {\n    const span = activeTracer.startSpan(name)\n    return context.with(TRACE_API.setSpan(context.active(), span), () => {\n      try {\n        const result = fn()\n        span.setStatus({ code: SpanStatusCode.OK })\n        return result\n      } catch (ex) {\n        const error = ex as Error\n        span.recordException(error)\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })\n        throw ex\n      } finally {\n        span.end()\n      }\n    })\n  } else {\n    return fn()\n  }\n}\n\nexport function spanRoot<T>(name: string, fn: () => T, tracer?: Tracer): T {\n  const activeTracer = tracer ?? TRACE_API.getTracer(name)\n  if (isDefined(activeTracer)) {\n    // Get current active context for configuration\n    const activeContext = context.active()\n\n    // Create a new context with no active span\n    const noSpanContext = cloneContextWithoutSpan(activeContext)\n\n    // Create a new span in the context without an active span\n    const span = activeTracer.startSpan(name, {}, noSpanContext)\n\n    // Use the active context but replace its span with our new root span\n    return context.with(TRACE_API.setSpan(noSpanContext, span), () => {\n      try {\n        const result = fn()\n        span.setStatus({ code: SpanStatusCode.OK })\n        return result\n      } catch (ex) {\n        const error = ex as Error\n        span.recordException(error)\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })\n        throw ex\n      } finally {\n        span.end()\n      }\n    })\n  } else {\n    return fn()\n  }\n}\n\nexport async function spanAsync<T>(\n  name: string,\n  fn: () => Promise<T>,\n  {\n    timeBudgetLimit, logger, tracer,\n  }: SpanConfig = {},\n): Promise<T> {\n  const activeTracer = tracer ?? TRACE_API.getTracer(name)\n  const funcToRun = isDefined(timeBudgetLimit) ? () => timeBudget(name, logger ?? console, fn, timeBudgetLimit) : fn\n  if (isDefined(activeTracer)) {\n    const span = activeTracer.startSpan(name)\n    return await context.with(TRACE_API.setSpan(context.active(), span), async () => {\n      try {\n        const result = await funcToRun()\n        span.setStatus({ code: SpanStatusCode.OK })\n        return result\n      } catch (ex) {\n        const error = ex as Error\n        span.recordException(error)\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })\n        throw ex\n      } finally {\n        span.end()\n      }\n    })\n  } else {\n    return await funcToRun()\n  }\n}\n\nexport async function spanRootAsync<T>(\n  name: string,\n  fn: () => Promise<T>,\n  {\n    timeBudgetLimit, logger, tracer,\n  }: SpanConfig = {},\n): Promise<T> {\n  const funcToRun = isDefined(timeBudgetLimit) ? () => timeBudget(name, logger ?? console, fn, timeBudgetLimit) : fn\n  const activeTracer = tracer ?? TRACE_API.getTracer(name)\n  if (isDefined(activeTracer)) {\n    const activeContext = context.active()\n\n    const noSpanContext = cloneContextWithoutSpan(activeContext)\n\n    // Create a new span in the context without an active span\n    const span = activeTracer.startSpan(name, {}, noSpanContext)\n\n    // Use the active context but replace its span with our new root span\n    return await context.with(TRACE_API.setSpan(noSpanContext, span), async () => {\n      try {\n        const result = await funcToRun()\n        span.setStatus({ code: SpanStatusCode.OK })\n        return result\n      } catch (ex) {\n        const error = ex as Error\n        span.recordException(error)\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })\n        throw ex\n      } finally {\n        span.end()\n      }\n    })\n  } else {\n    return await funcToRun()\n  }\n}\n","import type { Logger } from '@xylabs/logger'\n\nexport async function timeBudget<TResult>(\n  name: string,\n  logger: Logger | undefined,\n  func: () => Promise<TResult>,\n  budget: number,\n  status = false,\n): Promise<TResult> {\n  const start = Date.now()\n  const timer = status\n    ? setInterval(() => {\n        const duration = Date.now() - start\n        if ((budget > 0) && (duration > budget)) {\n          logger?.warn(`Function [${name}] execution is exceeding budget: ${duration}ms > ${budget}ms`)\n        }\n      }, Math.max(100, budget))\n    : undefined\n\n  const result = await func()\n  const duration = Date.now() - start\n\n  if (!timer && (budget > 0) && (duration > budget)) {\n    logger?.warn(`Function [${name}] execution exceeded budget: ${duration}ms > ${budget}ms`)\n  }\n  if (timer) {\n    clearInterval(timer)\n  }\n  return result\n}\n"],"mappings":";AAIA;AAAA,EACE;AAAA,EAAS;AAAA,EAAa;AAAA,EAAc;AAAA,EAAgB,SAAS;AAAA,OACxD;AAEP,SAAS,iBAAiB;;;ACN1B,eAAsB,WACpB,MACA,QACA,MACA,QACA,SAAS,OACS;AAClB,QAAM,QAAQ,KAAK,IAAI;AACvB,QAAM,QAAQ,SACV,YAAY,MAAM;AAChB,UAAMA,YAAW,KAAK,IAAI,IAAI;AAC9B,QAAK,SAAS,KAAOA,YAAW,QAAS;AACvC,cAAQ,KAAK,aAAa,IAAI,oCAAoCA,SAAQ,QAAQ,MAAM,IAAI;AAAA,IAC9F;AAAA,EACF,GAAG,KAAK,IAAI,KAAK,MAAM,CAAC,IACxB;AAEJ,QAAM,SAAS,MAAM,KAAK;AAC1B,QAAM,WAAW,KAAK,IAAI,IAAI;AAE9B,MAAI,CAAC,SAAU,SAAS,KAAO,WAAW,QAAS;AACjD,YAAQ,KAAK,aAAa,IAAI,gCAAgC,QAAQ,QAAQ,MAAM,IAAI;AAAA,EAC1F;AACA,MAAI,OAAO;AACT,kBAAc,KAAK;AAAA,EACrB;AACA,SAAO;AACT;;;ADXO,SAAS,wBAAwB,WAAoB,aAAuB,CAAC,GAAY;AAE9F,MAAI,SAAS;AAGb,QAAM,UAAU,YAAY,WAAW,SAAS;AAChD,MAAI,SAAS;AACX,aAAS,YAAY,WAAW,QAAQ,OAAO;AAAA,EACjD;AAGA,aAAW,OAAO,YAAY;AAC5B,UAAM,QAAQ,UAAU,SAAS,GAAG;AACpC,QAAI,UAAU,QAAW;AACvB,eAAS,OAAO,SAAS,KAAK,KAAK;AAAA,IACrC;AAAA,EACF;AAEA,SAAO;AACT;AAEO,SAAS,KAAQ,MAAc,IAAa,QAAoB;AACrE,QAAM,eAAe,UAAU,UAAU,UAAU,IAAI;AACvD,MAAI,UAAU,YAAY,GAAG;AAC3B,UAAMC,QAAO,aAAa,UAAU,IAAI;AACxC,WAAO,QAAQ,KAAK,UAAU,QAAQ,QAAQ,OAAO,GAAGA,KAAI,GAAG,MAAM;AACnE,UAAI;AACF,cAAM,SAAS,GAAG;AAClB,QAAAA,MAAK,UAAU,EAAE,MAAM,eAAe,GAAG,CAAC;AAC1C,eAAO;AAAA,MACT,SAAS,IAAI;AACX,cAAM,QAAQ;AACd,QAAAA,MAAK,gBAAgB,KAAK;AAC1B,QAAAA,MAAK,UAAU,EAAE,MAAM,eAAe,OAAO,SAAS,MAAM,QAAQ,CAAC;AACrE,cAAM;AAAA,MACR,UAAE;AACA,QAAAA,MAAK,IAAI;AAAA,MACX;AAAA,IACF,CAAC;AAAA,EACH,OAAO;AACL,WAAO,GAAG;AAAA,EACZ;AACF;AAEO,SAAS,SAAY,MAAc,IAAa,QAAoB;AACzE,QAAM,eAAe,UAAU,UAAU,UAAU,IAAI;AACvD,MAAI,UAAU,YAAY,GAAG;AAE3B,UAAM,gBAAgB,QAAQ,OAAO;AAGrC,UAAM,gBAAgB,wBAAwB,aAAa;AAG3D,UAAMA,QAAO,aAAa,UAAU,MAAM,CAAC,GAAG,aAAa;AAG3D,WAAO,QAAQ,KAAK,UAAU,QAAQ,eAAeA,KAAI,GAAG,MAAM;AAChE,UAAI;AACF,cAAM,SAAS,GAAG;AAClB,QAAAA,MAAK,UAAU,EAAE,MAAM,eAAe,GAAG,CAAC;AAC1C,eAAO;AAAA,MACT,SAAS,IAAI;AACX,cAAM,QAAQ;AACd,QAAAA,MAAK,gBAAgB,KAAK;AAC1B,QAAAA,MAAK,UAAU,EAAE,MAAM,eAAe,OAAO,SAAS,MAAM,QAAQ,CAAC;AACrE,cAAM;AAAA,MACR,UAAE;AACA,QAAAA,MAAK,IAAI;AAAA,MACX;AAAA,IACF,CAAC;AAAA,EACH,OAAO;AACL,WAAO,GAAG;AAAA,EACZ;AACF;AAEA,eAAsB,UACpB,MACA,IACA;AAAA,EACE;AAAA,EAAiB;AAAA,EAAQ;AAC3B,IAAgB,CAAC,GACL;AACZ,QAAM,eAAe,UAAU,UAAU,UAAU,IAAI;AACvD,QAAM,YAAY,UAAU,eAAe,IAAI,MAAM,WAAW,MAAM,UAAU,SAAS,IAAI,eAAe,IAAI;AAChH,MAAI,UAAU,YAAY,GAAG;AAC3B,UAAMA,QAAO,aAAa,UAAU,IAAI;AACxC,WAAO,MAAM,QAAQ,KAAK,UAAU,QAAQ,QAAQ,OAAO,GAAGA,KAAI,GAAG,YAAY;AAC/E,UAAI;AACF,cAAM,SAAS,MAAM,UAAU;AAC/B,QAAAA,MAAK,UAAU,EAAE,MAAM,eAAe,GAAG,CAAC;AAC1C,eAAO;AAAA,MACT,SAAS,IAAI;AACX,cAAM,QAAQ;AACd,QAAAA,MAAK,gBAAgB,KAAK;AAC1B,QAAAA,MAAK,UAAU,EAAE,MAAM,eAAe,OAAO,SAAS,MAAM,QAAQ,CAAC;AACrE,cAAM;AAAA,MACR,UAAE;AACA,QAAAA,MAAK,IAAI;AAAA,MACX;AAAA,IACF,CAAC;AAAA,EACH,OAAO;AACL,WAAO,MAAM,UAAU;AAAA,EACzB;AACF;AAEA,eAAsB,cACpB,MACA,IACA;AAAA,EACE;AAAA,EAAiB;AAAA,EAAQ;AAC3B,IAAgB,CAAC,GACL;AACZ,QAAM,YAAY,UAAU,eAAe,IAAI,MAAM,WAAW,MAAM,UAAU,SAAS,IAAI,eAAe,IAAI;AAChH,QAAM,eAAe,UAAU,UAAU,UAAU,IAAI;AACvD,MAAI,UAAU,YAAY,GAAG;AAC3B,UAAM,gBAAgB,QAAQ,OAAO;AAErC,UAAM,gBAAgB,wBAAwB,aAAa;AAG3D,UAAMA,QAAO,aAAa,UAAU,MAAM,CAAC,GAAG,aAAa;AAG3D,WAAO,MAAM,QAAQ,KAAK,UAAU,QAAQ,eAAeA,KAAI,GAAG,YAAY;AAC5E,UAAI;AACF,cAAM,SAAS,MAAM,UAAU;AAC/B,QAAAA,MAAK,UAAU,EAAE,MAAM,eAAe,GAAG,CAAC;AAC1C,eAAO;AAAA,MACT,SAAS,IAAI;AACX,cAAM,QAAQ;AACd,QAAAA,MAAK,gBAAgB,KAAK;AAC1B,QAAAA,MAAK,UAAU,EAAE,MAAM,eAAe,OAAO,SAAS,MAAM,QAAQ,CAAC;AACrE,cAAM;AAAA,MACR,UAAE;AACA,QAAAA,MAAK,IAAI;AAAA,MACX;AAAA,IACF,CAAC;AAAA,EACH,OAAO;AACL,WAAO,MAAM,UAAU;AAAA,EACzB;AACF;","names":["duration","span"]}
+{"version":3,"sources":["../../src/span.ts","../../src/timeBudget.ts"],"sourcesContent":["import type {\n  Context,\n  Tracer,\n} from '@opentelemetry/api'\nimport {\n  context, propagation, ROOT_CONTEXT, SpanStatusCode, trace as TRACE_API,\n} from '@opentelemetry/api'\nimport type { Logger } from '@xylabs/logger'\nimport { isDefined } from '@xylabs/typeof'\n\nimport { timeBudget } from './timeBudget.ts'\n\n/** Configuration options for span creation and execution. */\nexport interface SpanConfig {\n  /** Optional logger for time budget warnings. Falls back to console if not provided. */\n  logger?: Logger | null\n  /** Maximum allowed execution time in milliseconds before logging a warning. */\n  timeBudgetLimit?: number\n  /** OpenTelemetry tracer to use. Defaults to a tracer named after the span. */\n  tracer?: Tracer\n}\n\n/**\n * Creates a new OpenTelemetry context that preserves baggage and custom keys but has no active span.\n * @param activeCtx - The context to clone from.\n * @param configKeys - Additional context keys to copy.\n * @returns A new context with baggage but no parent span.\n */\nexport function cloneContextWithoutSpan(activeCtx: Context, configKeys: symbol[] = []): Context {\n  // Start from root to ensure no span is propagated\n  let newCtx = ROOT_CONTEXT\n\n  // Copy baggage\n  const baggage = propagation.getBaggage(activeCtx)\n  if (baggage) {\n    newCtx = propagation.setBaggage(newCtx, baggage)\n  }\n\n  // Copy custom config keys\n  for (const key of configKeys) {\n    const value = activeCtx.getValue(key)\n    if (value !== undefined) {\n      newCtx = newCtx.setValue(key, value)\n    }\n  }\n\n  return newCtx\n}\n\n/**\n * Executes a synchronous function within an OpenTelemetry span, recording status and exceptions.\n * @param name - The span name.\n * @param fn - The function to execute.\n * @param tracer - Optional tracer to use.\n * @returns The return value of `fn`.\n */\nexport function span<T>(name: string, fn: () => T, tracer?: Tracer): T {\n  const activeTracer = tracer ?? TRACE_API.getTracer(name)\n  if (isDefined(activeTracer)) {\n    const span = activeTracer.startSpan(name)\n    return context.with(TRACE_API.setSpan(context.active(), span), () => {\n      try {\n        const result = fn()\n        span.setStatus({ code: SpanStatusCode.OK })\n        return result\n      } catch (ex) {\n        const error = ex as Error\n        span.recordException(error)\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })\n        throw ex\n      } finally {\n        span.end()\n      }\n    })\n  } else {\n    return fn()\n  }\n}\n\n/**\n * Executes a synchronous function within a new root span that has no parent, even if a span is already active.\n * @param name - The span name.\n * @param fn - The function to execute.\n * @param tracer - Optional tracer to use.\n * @returns The return value of `fn`.\n */\nexport function spanRoot<T>(name: string, fn: () => T, tracer?: Tracer): T {\n  const activeTracer = tracer ?? TRACE_API.getTracer(name)\n  if (isDefined(activeTracer)) {\n    // Get current active context for configuration\n    const activeContext = context.active()\n\n    // Create a new context with no active span\n    const noSpanContext = cloneContextWithoutSpan(activeContext)\n\n    // Create a new span in the context without an active span\n    const span = activeTracer.startSpan(name, {}, noSpanContext)\n\n    // Use the active context but replace its span with our new root span\n    return context.with(TRACE_API.setSpan(noSpanContext, span), () => {\n      try {\n        const result = fn()\n        span.setStatus({ code: SpanStatusCode.OK })\n        return result\n      } catch (ex) {\n        const error = ex as Error\n        span.recordException(error)\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })\n        throw ex\n      } finally {\n        span.end()\n      }\n    })\n  } else {\n    return fn()\n  }\n}\n\n/**\n * Executes an async function within an OpenTelemetry span, with optional time budget monitoring.\n * @param name - The span name.\n * @param fn - The async function to execute.\n * @param config - Optional span configuration (tracer, logger, time budget).\n * @returns The resolved value of `fn`.\n */\nexport async function spanAsync<T>(\n  name: string,\n  fn: () => Promise<T>,\n  {\n    timeBudgetLimit, logger, tracer,\n  }: SpanConfig = {},\n): Promise<T> {\n  const activeTracer = tracer ?? TRACE_API.getTracer(name)\n  const funcToRun = isDefined(timeBudgetLimit) ? () => timeBudget(name, logger ?? console, fn, timeBudgetLimit) : fn\n  if (isDefined(activeTracer)) {\n    const span = activeTracer.startSpan(name)\n    return await context.with(TRACE_API.setSpan(context.active(), span), async () => {\n      try {\n        const result = await funcToRun()\n        span.setStatus({ code: SpanStatusCode.OK })\n        return result\n      } catch (ex) {\n        const error = ex as Error\n        span.recordException(error)\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })\n        throw ex\n      } finally {\n        span.end()\n      }\n    })\n  } else {\n    return await funcToRun()\n  }\n}\n\n/**\n * Executes an async function within a new root span (no parent), with optional time budget monitoring.\n * @param name - The span name.\n * @param fn - The async function to execute.\n * @param config - Optional span configuration (tracer, logger, time budget).\n * @returns The resolved value of `fn`.\n */\nexport async function spanRootAsync<T>(\n  name: string,\n  fn: () => Promise<T>,\n  {\n    timeBudgetLimit, logger, tracer,\n  }: SpanConfig = {},\n): Promise<T> {\n  const funcToRun = isDefined(timeBudgetLimit) ? () => timeBudget(name, logger ?? console, fn, timeBudgetLimit) : fn\n  const activeTracer = tracer ?? TRACE_API.getTracer(name)\n  if (isDefined(activeTracer)) {\n    const activeContext = context.active()\n\n    const noSpanContext = cloneContextWithoutSpan(activeContext)\n\n    // Create a new span in the context without an active span\n    const span = activeTracer.startSpan(name, {}, noSpanContext)\n\n    // Use the active context but replace its span with our new root span\n    return await context.with(TRACE_API.setSpan(noSpanContext, span), async () => {\n      try {\n        const result = await funcToRun()\n        span.setStatus({ code: SpanStatusCode.OK })\n        return result\n      } catch (ex) {\n        const error = ex as Error\n        span.recordException(error)\n        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })\n        throw ex\n      } finally {\n        span.end()\n      }\n    })\n  } else {\n    return await funcToRun()\n  }\n}\n","import type { Logger } from '@xylabs/logger'\n\n/**\n * Executes an async function and logs a warning if it exceeds the given time budget.\n * @param name - A label for the function, used in warning messages.\n * @param logger - The logger to use for budget-exceeded warnings.\n * @param func - The async function to execute.\n * @param budget - The time budget in milliseconds.\n * @param status - If true, logs periodic warnings while the function is still running.\n * @returns The result of the executed function.\n */\nexport async function timeBudget<TResult>(\n  name: string,\n  logger: Logger | undefined,\n  func: () => Promise<TResult>,\n  budget: number,\n  status = false,\n): Promise<TResult> {\n  const start = Date.now()\n  const timer = status\n    ? setInterval(() => {\n        const duration = Date.now() - start\n        if ((budget > 0) && (duration > budget)) {\n          logger?.warn(`Function [${name}] execution is exceeding budget: ${duration}ms > ${budget}ms`)\n        }\n      }, Math.max(100, budget))\n    : undefined\n\n  const result = await func()\n  const duration = Date.now() - start\n\n  if (!timer && (budget > 0) && (duration > budget)) {\n    logger?.warn(`Function [${name}] execution exceeded budget: ${duration}ms > ${budget}ms`)\n  }\n  if (timer) {\n    clearInterval(timer)\n  }\n  return result\n}\n"],"mappings":"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","names":["duration","span"]}

package/dist/neutral/span.d.ts

@@ -1,13 +1,51 @@
 import type { Context, Tracer } from '@opentelemetry/api';
 import type { Logger } from '@xylabs/logger';
+/** Configuration options for span creation and execution. */
 export interface SpanConfig {
+    /** Optional logger for time budget warnings. Falls back to console if not provided. */
     logger?: Logger | null;
+    /** Maximum allowed execution time in milliseconds before logging a warning. */
     timeBudgetLimit?: number;
+    /** OpenTelemetry tracer to use. Defaults to a tracer named after the span. */
     tracer?: Tracer;
 }
+/**
+ * Creates a new OpenTelemetry context that preserves baggage and custom keys but has no active span.
+ * @param activeCtx - The context to clone from.
+ * @param configKeys - Additional context keys to copy.
+ * @returns A new context with baggage but no parent span.
+ */
 export declare function cloneContextWithoutSpan(activeCtx: Context, configKeys?: symbol[]): Context;
+/**
+ * Executes a synchronous function within an OpenTelemetry span, recording status and exceptions.
+ * @param name - The span name.
+ * @param fn - The function to execute.
+ * @param tracer - Optional tracer to use.
+ * @returns The return value of `fn`.
+ */
 export declare function span<T>(name: string, fn: () => T, tracer?: Tracer): T;
+/**
+ * Executes a synchronous function within a new root span that has no parent, even if a span is already active.
+ * @param name - The span name.
+ * @param fn - The function to execute.
+ * @param tracer - Optional tracer to use.
+ * @returns The return value of `fn`.
+ */
 export declare function spanRoot<T>(name: string, fn: () => T, tracer?: Tracer): T;
+/**
+ * Executes an async function within an OpenTelemetry span, with optional time budget monitoring.
+ * @param name - The span name.
+ * @param fn - The async function to execute.
+ * @param config - Optional span configuration (tracer, logger, time budget).
+ * @returns The resolved value of `fn`.
+ */
 export declare function spanAsync<T>(name: string, fn: () => Promise<T>, { timeBudgetLimit, logger, tracer, }?: SpanConfig): Promise<T>;
+/**
+ * Executes an async function within a new root span (no parent), with optional time budget monitoring.
+ * @param name - The span name.
+ * @param fn - The async function to execute.
+ * @param config - Optional span configuration (tracer, logger, time budget).
+ * @returns The resolved value of `fn`.
+ */
 export declare function spanRootAsync<T>(name: string, fn: () => Promise<T>, { timeBudgetLimit, logger, tracer, }?: SpanConfig): Promise<T>;
 //# sourceMappingURL=span.d.ts.map

package/dist/neutral/span.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"span.d.ts","sourceRoot":"","sources":["../../src/span.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,MAAM,EACP,MAAM,oBAAoB,CAAA;AAI3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAK5C,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,GAAE,MAAM,EAAO,GAAG,OAAO,CAmB9F;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAqBrE;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CA8BzE;AAED,wBAAsB,SAAS,CAAC,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,EACE,eAAe,EAAE,MAAM,EAAE,MAAM,GAChC,GAAE,UAAe,GACjB,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,EACE,eAAe,EAAE,MAAM,EAAE,MAAM,GAChC,GAAE,UAAe,GACjB,OAAO,CAAC,CAAC,CAAC,CA6BZ"}
+{"version":3,"file":"span.d.ts","sourceRoot":"","sources":["../../src/span.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,MAAM,EACP,MAAM,oBAAoB,CAAA;AAI3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAK5C,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,GAAE,MAAM,EAAO,GAAG,OAAO,CAmB9F;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAqBrE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CA8BzE;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,EACE,eAAe,EAAE,MAAM,EAAE,MAAM,GAChC,GAAE,UAAe,GACjB,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,EACE,eAAe,EAAE,MAAM,EAAE,MAAM,GAChC,GAAE,UAAe,GACjB,OAAO,CAAC,CAAC,CAAC,CA6BZ"}

package/dist/neutral/timeBudget.d.ts

@@ -1,3 +1,12 @@
 import type { Logger } from '@xylabs/logger';
+/**
+ * Executes an async function and logs a warning if it exceeds the given time budget.
+ * @param name - A label for the function, used in warning messages.
+ * @param logger - The logger to use for budget-exceeded warnings.
+ * @param func - The async function to execute.
+ * @param budget - The time budget in milliseconds.
+ * @param status - If true, logs periodic warnings while the function is still running.
+ * @returns The result of the executed function.
+ */
 export declare function timeBudget<TResult>(name: string, logger: Logger | undefined, func: () => Promise<TResult>, budget: number, status?: boolean): Promise<TResult>;
 //# sourceMappingURL=timeBudget.d.ts.map

package/dist/neutral/timeBudget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeBudget.d.ts","sourceRoot":"","sources":["../../src/timeBudget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAE5C,wBAAsB,UAAU,CAAC,OAAO,EACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC5B,MAAM,EAAE,MAAM,EACd,MAAM,UAAQ,GACb,OAAO,CAAC,OAAO,CAAC,CAqBlB"}
+{"version":3,"file":"timeBudget.d.ts","sourceRoot":"","sources":["../../src/timeBudget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAE5C;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAAC,OAAO,EACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EAC5B,MAAM,EAAE,MAAM,EACd,MAAM,UAAQ,GACb,OAAO,CAAC,OAAO,CAAC,CAqBlB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/telemetry",
-  "version": "5.0.83",
+  "version": "5.0.84",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "keywords": [
     "hex",
@@ -43,12 +43,12 @@
   ],
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@xylabs/logger": "~5.0.83",
-    "@xylabs/typeof": "~5.0.83"
+    "@xylabs/logger": "~5.0.84",
+    "@xylabs/typeof": "~5.0.84"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "~7.4.11",
-    "@xylabs/tsconfig": "~7.4.11",
+    "@xylabs/ts-scripts-yarn3": "~7.4.13",
+    "@xylabs/tsconfig": "~7.4.13",
     "typescript": "~5.9.3",
     "vitest": "~4.0.18"
   },