TypeScript reference

Generated from the @glassflow-ai/rius 0.2.4 type declarations, covering the TypeScript SDK’s public API surface. Wording fixes happen upstream in the SDK repository, never here.

Most code starts with init(), then observe() or the startSpan / startGeneration helpers. RiusClient is the handle init() returns; the rest are the option shapes those take.

getTracer()


function getTracer(): Tracer;

The SDK tracer. Scope name is wire-visible; do not parameterize it.

Returns

Tracer

init()


function init(options?): RiusClient;

Initialize the SDK: build a tracer pipeline that exports OTLP traces and enable every bundled auto-instrumentation whose package is installed.

Call it once, as early as possible in your process. A second call while a client is active logs a warning and returns the existing client unchanged; shutdown() releases the slot. init() is synchronous; await RiusClient.ready if instrumentation must be attached before your first span.

The SDK installs no process exit hook: short-lived processes must call RiusClient.flush before exiting or spans still in the batch queue are lost.

Parameters

Parameter	Type
`options?`	`InitOptions`

Returns

RiusClient

observe()


function observe<F>(fn, options?): (...args) => Promise<Awaited<ReturnType<F>>>;

Wrap a function so each call becomes a span. Returns a function with the same signature, so call sites and types are unchanged.

A wrapper rather than a decorator on purpose: TypeScript decorators apply only to class members, and most agent code is plain functions.

Type Parameters

Type Parameter
`F` extends (…`args`) => `unknown`

Parameters

Parameter	Type
`fn`	`F`
`options?`	`ObserveOptions`

Returns


(...args): Promise<Awaited<ReturnType<F>>>;

Parameters

Parameter	Type
…`args`	`Parameters`<`F`>

Returns

Promise<Awaited<ReturnType<F>>>

startAsCurrentGeneration()

Call Signature


function startAsCurrentGeneration<T>(name, fn): Promise<T>;

Run fn with a generation span active. Auto-ends, records exceptions.

options is optional, so startAsCurrentGeneration(name, fn) works without an empty object. The callback stays last.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`name`	`string`
`fn`	`GenerationBody`<`T`>

Returns

Promise<T>

Call Signature


function startAsCurrentGeneration<T>(
   name, 
   options, 
fn): Promise<T>;

Run fn with a generation span active. Auto-ends, records exceptions.

options is optional, so startAsCurrentGeneration(name, fn) works without an empty object. The callback stays last.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`name`	`string`
`options`	`GenerationOptions`
`fn`	`GenerationBody`<`T`>

Returns

Promise<T>

startAsCurrentSpan()

Call Signature


function startAsCurrentSpan<T>(name, fn): Promise<T>;

Run fn with a new span active, so spans created inside it nest under this one across async boundaries. Auto-ends, records exceptions, rethrows.

options is optional, so the common case is startAsCurrentSpan(name, fn) rather than startAsCurrentSpan(name, {}, fn). The callback stays last.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`name`	`string`
`fn`	`SpanBody`<`T`>

Returns

Promise<T>

Call Signature


function startAsCurrentSpan<T>(
   name, 
   options, 
fn): Promise<T>;

Run fn with a new span active, so spans created inside it nest under this one across async boundaries. Auto-ends, records exceptions, rethrows.

options is optional, so the common case is startAsCurrentSpan(name, fn) rather than startAsCurrentSpan(name, {}, fn). The callback stays last.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`name`	`string`
`options`	`SpanOptions`
`fn`	`SpanBody`<`T`>

Returns

Promise<T>

startGeneration()


function startGeneration(name, options?): Generation;

Create a generation span and return a handle. You MUST call end().

Parameters

Parameter	Type
`name`	`string`
`options?`	`GenerationOptions`

Returns

Generation

startSpan()


function startSpan(name, options?): Observation;

Create a span and return a handle. You MUST call end() (or use using). The span is parented to whatever is current but does NOT become current.

Parameters

Parameter	Type
`name`	`string`
`options?`	`SpanOptions`

Returns

Observation

Generation

An LLM call. Content uses gen_ai message keys, never input.value.

Extends

Observation

Constructors

Constructor


new Generation(span): Generation;

Parameters

Parameter	Type
`span`	`Span`

Returns

Generation

Inherited from

Observation.constructor

Methods

[dispose]()


dispose: void;

Lets callers write using obs = startSpan(...). Sugar over end().

Returns

void

Inherited from

Observation.[dispose]

end()


end(): void;

Returns

void

Inherited from

Observation.end

recordException()


recordException(error): this;

Record an error on the span and set ERROR status. This is exactly what the startAsCurrent* helpers do on a thrown error, exposed so the manual start* path does not have to reach through .span to match it.

Accepts unknown because that is what a catch binding is; a non-Error throwable is wrapped so recordException still gets a real Error.

Parameters

Parameter	Type
`error`	`unknown`

Returns

this

Inherited from

Observation.recordException

recordFirstToken()


recordFirstToken(): this;

The TTFT anchor: event time minus span start. Idempotent: only the first call records the event, so a streaming loop can call this unconditionally on every chunk without inflating the span. A no-op after the span has ended.

Returns

this

setAttribute()


setAttribute(key, value): this;

Parameters

Parameter	Type
`key`	`string`
`value`	`unknown`

Returns

this

Inherited from

Observation.setAttribute

setFinishReasons()


setFinishReasons(reasons): this;

Why generation stopped (gen_ai.response.finish_reasons), e.g. "stop", "length", "tool_calls". The convention is a list; a single reason is wrapped so callers do not have to.

Parameters

Parameter	Type
`reasons`	`string` \| `string`[]

Returns

this

setInput()


setInput(value): this;

Parameters

Parameter	Type
`value`	`unknown`

Returns

this

Overrides

Observation.setInput

setModel()


setModel(model): this;

Parameters

Parameter	Type
`model`	`string`

Returns

this

setOutput()


setOutput(value): this;

Parameters

Parameter	Type
`value`	`unknown`

Returns

this

Overrides

Observation.setOutput

setUsage()


setUsage(usage): this;

Parameters

Parameter	Type
`usage`	{ `inputTokens?`: `number`; `outputTokens?`: `number`; }
`usage.inputTokens?`	`number`
`usage.outputTokens?`	`number`

Returns

this

Properties

Property	Modifier	Type	Inherited from
`span`	`readonly`	`Span`	`Observation`.`span`

Observation

A handle over a span. Chainable setters; end() is idempotent.

Extended by

Generation

Constructors

Constructor


new Observation(span): Observation;

Parameters

Parameter	Type
`span`	`Span`

Returns

Observation

Methods

[dispose]()


dispose: void;

Lets callers write using obs = startSpan(...). Sugar over end().

Returns

void

end()


end(): void;

Returns

void

recordException()


recordException(error): this;

Accepts unknown because that is what a catch binding is; a non-Error throwable is wrapped so recordException still gets a real Error.

Parameters

Parameter	Type
`error`	`unknown`

Returns

this

setAttribute()


setAttribute(key, value): this;

Parameters

Parameter	Type
`key`	`string`
`value`	`unknown`

Returns

this

setInput()


setInput(value): this;

Parameters

Parameter	Type
`value`	`unknown`

Returns

this

setOutput()


setOutput(value): this;

Parameters

Parameter	Type
`value`	`unknown`

Returns

this

Properties

Property	Modifier	Type
`span`	`readonly`	`Span`

RiusClient

Handle over a configured tracer pipeline, returned by init. Exposes the lifecycle operations (flush, shutdown) and ready, which resolves with the auto-instrumentations that attached.

Methods

flush()


flush(): Promise<boolean>;

Drains the queue. Resolves false if the most recent export failed.

Returns

Promise<boolean>

shutdown()


shutdown(): Promise<void>;

Drains and tears down the provider, then releases the global registration so a later init() can reconfigure the SDK.

The heartbeat’s final stopped: true ping is sent before the provider shuts down, so the backend hears “stopped” while the trace pipeline can still export it. Idempotent: sender.stop() no-ops on a second call, and the beforeExit listener is removed here so repeated init/shutdown cycles never leak listeners.

Returns

Promise<void>

Properties

Property	Modifier	Type	Description
`ready`	`readonly`	`Promise`<`string`[]>	Resolves with the names of the auto-instrumentations that attached.

GenerationOptions

Options for startGeneration and startAsCurrentGeneration: the model identity and request parameters an LLM span carries.

Properties

Property	Type	Description
`input?`	`unknown`	-
`model?`	`string`	-
`modelParameters?`	`Record`<`string`, `unknown`>	Request parameters, each recorded as `gen_ai.request.<key>` — for example `{ temperature: 0.2, max_tokens: 512 }`. Keys are passed through verbatim, so use the provider’s own parameter names.
`provider?`	`string`	-

InitOptions

Options accepted by init, extending the shared configuration.

Extends

RiusOptions

Properties

Property	Type	Description	Inherited from
`agentName?`	`string`	-	`RiusOptions`.`agentName`
`apiKey?`	`string`	-	`RiusOptions`.`apiKey`
`captureContent?`	`boolean`	-	`RiusOptions`.`captureContent`
`disabled?`	`boolean`	-	`RiusOptions`.`disabled`
`endpoint?`	`string`	-	`RiusOptions`.`endpoint`
`heartbeat?`	`boolean`	-	`RiusOptions`.`heartbeat`
`heartbeatInterval?`	`number`	Seconds between agent-lifetime heartbeat pings.	`RiusOptions`.`heartbeatInterval`
`heartbeatTransport?`	`HeartbeatTransport`	Override the heartbeat HTTP transport. The test seam; prefer this to mocking fetch.	-
`mask?`	`Mask`	-	`RiusOptions`.`mask`
`partialSpans?`	`boolean`	-	`RiusOptions`.`partialSpans`
`partialSpansDelay?`	`number`	Seconds to debounce a pending-span snapshot after span start.	`RiusOptions`.`partialSpansDelay`
`sampleRate?`	`number`	-	`RiusOptions`.`sampleRate`
`serviceName?`	`string`	-	`RiusOptions`.`serviceName`
`spanExporter?`	`SpanExporter`	Inject an exporter instead of OTLP. The test seam; prefer this to mocking.	-

ObserveOptions

Options for observe.

Properties

Property	Type
`captureInput?`	`boolean`
`captureOutput?`	`boolean`
`kind?`	`SpanKind`
`name?`	`string`

RiusOptions

Configuration shared by every client. Each option can also come from a RIUS_* environment variable; explicit options win over the environment, which wins over defaults.

Extended by

InitOptions

Properties

Property	Type	Description
`agentName?`	`string`	-
`apiKey?`	`string`	-
`captureContent?`	`boolean`	-
`disabled?`	`boolean`	-
`endpoint?`	`string`	-
`heartbeat?`	`boolean`	-
`heartbeatInterval?`	`number`	Seconds between agent-lifetime heartbeat pings.
`mask?`	`Mask`	-
`partialSpans?`	`boolean`	-
`partialSpansDelay?`	`number`	Seconds to debounce a pending-span snapshot after span start.
`sampleRate?`	`number`	-
`serviceName?`	`string`	-

SpanOptions

Options for startSpan and startAsCurrentSpan.

Properties

Property	Type
`input?`	`unknown`
`kind?`	`SpanKind`

GenerationBody()


type GenerationBody<T> = (generation) => Promise<T> | T;

The body of a scoped generation.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`generation`	`Generation`

Returns

Promise<T> | T

Mask()


type Mask = (value, context?) => unknown;

Redacts content attribute values at export. Receives the key when it accepts one.

Parameters

Parameter	Type
`value`	`unknown`
`context?`	{ `key`: `string`; }
`context.key?`	`string`

Returns

unknown

SpanBody()


type SpanBody<T> = (observation) => Promise<T> | T;

The body of a scoped span.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`observation`	`Observation`

Returns

Promise<T> | T

SpanKind

Observation kind. Values are OpenInference openinference.span.kind values, the taxonomy the platform’s agent analytics group by.

Enumeration Members

Enumeration Member	Value
`AGENT`	`"AGENT"`
`CHAIN`	`"CHAIN"`
`EMBEDDING`	`"EMBEDDING"`
`LLM`	`"LLM"`
`RETRIEVER`	`"RETRIEVER"`
`TOOL`	`"TOOL"`

VERSION


const VERSION: "0.2.4" = "0.2.4";