@xylabs/telemetry 5.0.79 → 5.0.81

package/README.md

@@ -21,6 +21,10 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ***
 
+## Interfaces
+
+- [SpanConfig](#interfaces/SpanConfig)
+
 ## Functions
 
 - [cloneContextWithoutSpan](#functions/cloneContextWithoutSpan)
@@ -28,6 +32,7 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 - [spanRoot](#functions/spanRoot)
 - [spanAsync](#functions/spanAsync)
 - [spanRootAsync](#functions/spanRootAsync)
+- [timeBudget](#functions/timeBudget)
 
 ### functions
 
@@ -38,7 +43,7 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 ***
 
 ```ts
-function cloneContextWithoutSpan(activeCtx, configKeys): Context;
+function cloneContextWithoutSpan(activeCtx, configKeys?): Context;
 ```
 
 ## Parameters
@@ -47,7 +52,7 @@ function cloneContextWithoutSpan(activeCtx, configKeys): Context;
 
 `Context`
 
-### configKeys
+### configKeys?
 
 `symbol`[] = `[]`
 
@@ -102,7 +107,7 @@ function span<T>(
 function spanAsync<T>(
    name, 
    fn, 
-tracer?): Promise<T>;
+__namedParameters?): Promise<T>;
 ```
 
 ## Type Parameters
@@ -121,9 +126,9 @@ tracer?): Promise<T>;
 
 () => `Promise`\<`T`\>
 
-### tracer?
+### \_\_namedParameters?
 
-`Tracer`
+[`SpanConfig`](#../interfaces/SpanConfig) = `{}`
 
 ## Returns
 
@@ -176,7 +181,7 @@ function spanRoot<T>(
 function spanRootAsync<T>(
    name, 
    fn, 
-tracer?): Promise<T>;
+__namedParameters?): Promise<T>;
 ```
 
 ## Type Parameters
@@ -195,14 +200,93 @@ tracer?): Promise<T>;
 
 () => `Promise`\<`T`\>
 
-### tracer?
+### \_\_namedParameters?
 
-`Tracer`
+[`SpanConfig`](#../interfaces/SpanConfig) = `{}`
 
 ## Returns
 
 `Promise`\<`T`\>
 
+  ### <a id="timeBudget"></a>timeBudget
+
+[**@xylabs/telemetry**](#../README)
+
+***
+
+```ts
+function timeBudget<TResult>(
+   name, 
+   logger, 
+   func, 
+   budget, 
+status?): Promise<TResult>;
+```
+
+## Type Parameters
+
+### TResult
+
+`TResult`
+
+## Parameters
+
+### name
+
+`string`
+
+### logger
+
+`Logger` | `undefined`
+
+### func
+
+() => `Promise`\<`TResult`\>
+
+### budget
+
+`number`
+
+### status?
+
+`boolean` = `false`
+
+## Returns
+
+`Promise`\<`TResult`\>
+
+### interfaces
+
+  ### <a id="SpanConfig"></a>SpanConfig
+
+[**@xylabs/telemetry**](#../README)
+
+***
+
+## Properties
+
+### logger?
+
+```ts
+optional logger: Logger | null;
+```
+
+***
+
+### timeBudgetLimit?
+
+```ts
+optional timeBudgetLimit: number;
+```
+
+***
+
+### tracer?
+
+```ts
+optional tracer: Tracer;
+```
+
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/telemetry",
-  "version": "5.0.79",
+  "version": "5.0.81",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "keywords": [
     "hex",
@@ -29,30 +29,28 @@
   "exports": {
     ".": {
       "types": "./dist/neutral/index.d.ts",
-      "source": "./src/index.ts",
       "default": "./dist/neutral/index.mjs"
     },
     "./package.json": "./package.json"
   },
   "module": "./dist/neutral/index.mjs",
-  "source": "./src/index.ts",
   "types": "./dist/neutral/index.d.ts",
   "files": [
     "dist",
-    "src",
     "!**/*.bench.*",
     "!**/*.spec.*",
     "!**/*.test.*"
   ],
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@xylabs/logger": "~5.0.79",
-    "@xylabs/typeof": "~5.0.79"
+    "@xylabs/logger": "~5.0.81",
+    "@xylabs/typeof": "~5.0.81"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "~7.3.2",
-    "@xylabs/tsconfig": "~7.3.2",
-    "typescript": "~5.9.3"
+    "@xylabs/ts-scripts-yarn3": "~7.4.11",
+    "@xylabs/tsconfig": "~7.4.11",
+    "typescript": "~5.9.3",
+    "vitest": "~4.0.18"
   },
   "engines": {
     "node": ">=18"

package/src/index.ts

@@ -1,2 +0,0 @@
-export * from './span.ts'
-export * from './timeBudget.ts'

package/src/span.ts

@@ -1,160 +0,0 @@
-import type {
-  Context,
-  Tracer,
-} from '@opentelemetry/api'
-import {
-  context, propagation, ROOT_CONTEXT, SpanStatusCode, trace as TRACE_API,
-} from '@opentelemetry/api'
-import type { Logger } from '@xylabs/logger'
-import { isDefined } from '@xylabs/typeof'
-
-import { timeBudget } from './timeBudget.ts'
-
-export interface SpanConfig {
-  logger?: Logger | null
-  timeBudgetLimit?: number
-  tracer?: Tracer
-}
-
-export function cloneContextWithoutSpan(activeCtx: Context, configKeys: symbol[] = []): Context {
-  // Start from root to ensure no span is propagated
-  let newCtx = ROOT_CONTEXT
-
-  // Copy baggage
-  const baggage = propagation.getBaggage(activeCtx)
-  if (baggage) {
-    newCtx = propagation.setBaggage(newCtx, baggage)
-  }
-
-  // Copy custom config keys
-  for (const key of configKeys) {
-    const value = activeCtx.getValue(key)
-    if (value !== undefined) {
-      newCtx = newCtx.setValue(key, value)
-    }
-  }
-
-  return newCtx
-}
-
-export function span<T>(name: string, fn: () => T, tracer?: Tracer): T {
-  const activeTracer = tracer ?? TRACE_API.getTracer(name)
-  if (isDefined(activeTracer)) {
-    const span = activeTracer.startSpan(name)
-    return context.with(TRACE_API.setSpan(context.active(), span), () => {
-      try {
-        const result = fn()
-        span.setStatus({ code: SpanStatusCode.OK })
-        return result
-      } catch (ex) {
-        const error = ex as Error
-        span.recordException(error)
-        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
-        throw ex
-      } finally {
-        span.end()
-      }
-    })
-  } else {
-    return fn()
-  }
-}
-
-export function spanRoot<T>(name: string, fn: () => T, tracer?: Tracer): T {
-  const activeTracer = tracer ?? TRACE_API.getTracer(name)
-  if (isDefined(activeTracer)) {
-    // Get current active context for configuration
-    const activeContext = context.active()
-
-    // Create a new context with no active span
-    const noSpanContext = cloneContextWithoutSpan(activeContext)
-
-    // Create a new span in the context without an active span
-    const span = activeTracer.startSpan(name, {}, noSpanContext)
-
-    // Use the active context but replace its span with our new root span
-    return context.with(TRACE_API.setSpan(noSpanContext, span), () => {
-      try {
-        const result = fn()
-        span.setStatus({ code: SpanStatusCode.OK })
-        return result
-      } catch (ex) {
-        const error = ex as Error
-        span.recordException(error)
-        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
-        throw ex
-      } finally {
-        span.end()
-      }
-    })
-  } else {
-    return fn()
-  }
-}
-
-export async function spanAsync<T>(
-  name: string,
-  fn: () => Promise<T>,
-  {
-    timeBudgetLimit, logger, tracer,
-  }: SpanConfig = {},
-): Promise<T> {
-  const activeTracer = tracer ?? TRACE_API.getTracer(name)
-  const funcToRun = isDefined(timeBudgetLimit) ? () => timeBudget(name, logger ?? console, fn, timeBudgetLimit) : fn
-  if (isDefined(activeTracer)) {
-    const span = activeTracer.startSpan(name)
-    return await context.with(TRACE_API.setSpan(context.active(), span), async () => {
-      try {
-        const result = await funcToRun()
-        span.setStatus({ code: SpanStatusCode.OK })
-        return result
-      } catch (ex) {
-        const error = ex as Error
-        span.recordException(error)
-        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
-        throw ex
-      } finally {
-        span.end()
-      }
-    })
-  } else {
-    return await funcToRun()
-  }
-}
-
-export async function spanRootAsync<T>(
-  name: string,
-  fn: () => Promise<T>,
-  {
-    timeBudgetLimit, logger, tracer,
-  }: SpanConfig = {},
-): Promise<T> {
-  const funcToRun = isDefined(timeBudgetLimit) ? () => timeBudget(name, logger ?? console, fn, timeBudgetLimit) : fn
-  const activeTracer = tracer ?? TRACE_API.getTracer(name)
-  if (isDefined(activeTracer)) {
-    const activeContext = context.active()
-
-    const noSpanContext = cloneContextWithoutSpan(activeContext)
-
-    // Create a new span in the context without an active span
-    const span = activeTracer.startSpan(name, {}, noSpanContext)
-
-    // Use the active context but replace its span with our new root span
-    return await context.with(TRACE_API.setSpan(noSpanContext, span), async () => {
-      try {
-        const result = await funcToRun()
-        span.setStatus({ code: SpanStatusCode.OK })
-        return result
-      } catch (ex) {
-        const error = ex as Error
-        span.recordException(error)
-        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message })
-        throw ex
-      } finally {
-        span.end()
-      }
-    })
-  } else {
-    return await funcToRun()
-  }
-}

package/src/timeBudget.ts

@@ -1,30 +0,0 @@
-import type { Logger } from '@xylabs/logger'
-
-export async function timeBudget<TResult>(
-  name: string,
-  logger: Logger | undefined,
-  func: () => Promise<TResult>,
-  budget: number,
-  status = false,
-): Promise<TResult> {
-  const start = Date.now()
-  const timer = status
-    ? setInterval(() => {
-        const duration = Date.now() - start
-        if ((budget > 0) && (duration > budget)) {
-          logger?.warn(`Function [${name}] execution is exceeding budget: ${duration}ms > ${budget}ms`)
-        }
-      }, Math.max(100, budget))
-    : undefined
-
-  const result = await func()
-  const duration = Date.now() - start
-
-  if (!timer && (budget > 0) && (duration > budget)) {
-    logger?.warn(`Function [${name}] execution exceeded budget: ${duration}ms > ${budget}ms`)
-  }
-  if (timer) {
-    clearInterval(timer)
-  }
-  return result
-}