@xylabs/telemetry

@xylabs/telemetry

Base functionality used throughout XY Labs TypeScript/JavaScript libraries

Install

Using npm:

npm install {{name}}

Using yarn:

yarn add {{name}}

Using pnpm:

pnpm add {{name}}

Using bun:

bun add {{name}}

License

See the LICENSE file for license rights and limitations (LGPL-3.0-only).

Reference

packages

telemetry

### .temp-typedoc

  ### functions

    ### <a id="cloneContextWithoutSpan"></a>cloneContextWithoutSpan

@xylabs/telemetry

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

function span<T>(
   name, 
   fn, 
   traceProvider?): T;

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

Type Parameters

T

T

Parameters

name

string

The span name.

fn

() => T

The function to execute.

traceProvider?

TracerProvider = TRACE_API

Returns

T

The return value of fn.

    ### <a id="spanAsync"></a>spanAsync

@xylabs/telemetry

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

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

Type Parameters

T

T

Parameters

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.

    ### <a id="spanRoot"></a>spanRoot

@xylabs/telemetry

function spanRoot<T>(
   name, 
   fn, 
   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

T

Parameters

name

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

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

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

Type Parameters

T

T

Parameters

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.

    ### <a id="timeBudget"></a>timeBudget

@xylabs/telemetry

function timeBudget<TResult>(
   name, 
   logger, 
   func, 
   budget, 
status?): Promise<TResult>;

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

Type Parameters

TResult

TResult

Parameters

name

string

A label for the function, used in warning messages.

logger

Logger | undefined

The logger to use for budget-exceeded warnings.

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

@xylabs/telemetry

Configuration options for span creation and execution.

Properties

logger?

optional logger?: Logger | null;

Optional logger for time budget warnings. Falls back to console if not provided.

timeBudgetLimit?

optional timeBudgetLimit?: number;

Maximum allowed execution time in milliseconds before logging a warning.

tracer?

optional tracer?: Tracer;

OpenTelemetry tracer to use. Defaults to a tracer named after the span.