@xylabs/telemetry

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

Reference

@xylabs/telemetry

Interfaces

| Interface | Description | | ------ | ------ | | SpanConfig | Configuration options for span creation and execution. |

Functions

| Function | Description | | ------ | ------ | | cloneContextWithoutSpan | Creates a new OpenTelemetry context that preserves baggage and custom keys but has no active span. | | span | Executes a synchronous function within an OpenTelemetry span, recording status and exceptions. | | spanRoot | Executes a synchronous function within a new root span that has no parent, even if a span is already active. | | spanAsync | Executes an async function within an OpenTelemetry span, with optional time budget monitoring. | | spanRootAsync | Executes an async function within a new root span (no parent), with optional time budget monitoring. | | timeBudget | Executes an async function and logs a warning if it exceeds the given time budget. |

functions

cloneContextWithoutSpan

@xylabs/telemetry

function cloneContextWithoutSpan(activeCtx: Context, configKeys?: symbol[]): Context;

Creates a new OpenTelemetry context that preserves baggage and custom keys but has no active span.

Parameters

| Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | | activeCtx | Context | undefined | The context to clone from. | | configKeys | symbol[] | [] | Additional context keys to copy. |

Returns

Context

A new context with baggage but no parent span.

span

@xylabs/telemetry

function span<T>(
   name: string, 
   fn: () => T, 
   tracer?: Tracer): T;

Executes a synchronous function within an OpenTelemetry span, recording status and exceptions.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | name | string | The span name. | | fn | () => T | The function to execute. | | tracer? | Tracer | Optional tracer to use. |

Returns

T

The return value of fn.

spanAsync

@xylabs/telemetry

function spanAsync<T>(
   name: string, 
   fn: () => Promise<T>, 
config?: SpanConfig): Promise<T>;

Executes an async function within an OpenTelemetry span, with optional time budget monitoring.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | name | string | The span name. | | fn | () => Promise<T> | The async function to execute. | | config | SpanConfig | Optional span configuration (tracer, logger, time budget). |

Returns

Promise<T>

The resolved value of fn.

spanRoot

@xylabs/telemetry

function spanRoot<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.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | name | string | The span name. | | fn | () => T | The function to execute. | | tracer? | Tracer | Optional tracer to use. |

Returns

T

The return value of fn.

spanRootAsync

@xylabs/telemetry

function spanRootAsync<T>(
   name: string, 
   fn: () => Promise<T>, 
config?: SpanConfig): Promise<T>;

Executes an async function within a new root span (no parent), with optional time budget monitoring.

Type Parameters

| Type Parameter | | ------ | | T |

Parameters

| Parameter | Type | Description | | ------ | ------ | ------ | | name | string | The span name. | | fn | () => Promise<T> | The async function to execute. | | config | SpanConfig | Optional span configuration (tracer, logger, time budget). |

Returns

Promise<T>

The resolved value of fn.

timeBudget

@xylabs/telemetry

function timeBudget<TResult>(
   name: string, 
   logger: Logger | undefined, 
   func: () => Promise<TResult>, 
   budget: number, 
status?: boolean): Promise<TResult>;

Executes an async function and logs a warning if it exceeds the given time budget.

Type Parameters

| Type Parameter | | ------ | | TResult |

Parameters

| Parameter | Type | Default value | Description | | ------ | ------ | ------ | ------ | | name | string | undefined | A label for the function, used in warning messages. | | logger | Logger | undefined | undefined | The logger to use for budget-exceeded warnings. | | func | () => Promise<TResult> | undefined | The async function to execute. | | budget | number | undefined | 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

SpanConfig

@xylabs/telemetry

Configuration options for span creation and execution.

Properties

| Property | Type | Description | | ------ | ------ | ------ | | logger? | Logger | null | Optional logger for time budget warnings. Falls back to console if not provided. | | timeBudgetLimit? | number | Maximum allowed execution time in milliseconds before logging a warning. | | tracer? | Tracer | OpenTelemetry tracer to use. Defaults to a tracer named after the span. |

Part of sdk-js

Maintainers

• Arie Trouw (arietrouw.com)
• Matt Jones
• Joel Carter
• Jordan Trouw

License

See the LICENSE file for license details

Credits

Made with 🔥 and ❄️ by XYLabs