TypeScript reference

Generated from the @glassflow-ai/rius 1.0.0 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 exit hook for SPANS: short-lived processes must call RiusClient.flush before exiting or spans still in the batch queue are lost. (The heartbeat does register a beforeExit listener, only to send its final stopped ping; it flushes nothing.)

Parameters

Returns

RiusClient

observe()

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

Wrap a function so each call becomes a span. The returned function takes the same parameters and always returns a Promise of the original’s result (a synchronous function becomes asynchronous), so call sites need an await but no other change.

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

Type Parameters

Parameters

Returns

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

Parameters

Returns

Promise<Awaited<ReturnType<F>>>

registerWorkspace()

function registerWorkspace(alias, apiKey): void;

Add (or rotate the key of) a workspace destination on the global client.

Requires init({ workspaces }) to have opted into routing (an empty object opts in with no static routes). Spans started inside withWorkspace(alias, ...) are then exported with apiKey.

Parameters

Returns

void

startAsCurrentGeneration()

Call Signature

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

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

Both the name and options are optional and the callback stays last, so startAsCurrentGeneration({ model: "gpt-4o" }, fn) names the span chat gpt-4o for you.

Type Parameters

Parameters

Returns

Promise<T>

Call Signature

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

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

Both the name and options are optional and the callback stays last, so startAsCurrentGeneration({ model: "gpt-4o" }, fn) names the span chat gpt-4o for you.

Type Parameters

Parameters

Returns

Promise<T>

Call Signature

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

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

Both the name and options are optional and the callback stays last, so startAsCurrentGeneration({ model: "gpt-4o" }, fn) names the span chat gpt-4o for you.

Type Parameters

Parameters

Returns

Promise<T>

Call Signature

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

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

Both the name and options are optional and the callback stays last, so startAsCurrentGeneration({ model: "gpt-4o" }, fn) names the span chat gpt-4o for you.

Type Parameters

Parameters

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.

Both the name and options are optional, and the callback always comes last: startAsCurrentSpan(name, fn), startAsCurrentSpan(options, fn) and startAsCurrentSpan(fn) all work, as does the full three-argument form. Omitting the name asks for the conventions’ {operation} {target} name; see startSpan.

Type Parameters

Parameters

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.

Both the name and options are optional, and the callback always comes last: startAsCurrentSpan(name, fn), startAsCurrentSpan(options, fn) and startAsCurrentSpan(fn) all work, as does the full three-argument form. Omitting the name asks for the conventions’ {operation} {target} name; see startSpan.

Type Parameters

Parameters

Returns

Promise<T>

Call Signature

function startAsCurrentSpan<T>(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.

Both the name and options are optional, and the callback always comes last: startAsCurrentSpan(name, fn), startAsCurrentSpan(options, fn) and startAsCurrentSpan(fn) all work, as does the full three-argument form. Omitting the name asks for the conventions’ {operation} {target} name; see startSpan.

Type Parameters

Parameters

Returns

Promise<T>

Call Signature

function startAsCurrentSpan<T>(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.

Both the name and options are optional, and the callback always comes last: startAsCurrentSpan(name, fn), startAsCurrentSpan(options, fn) and startAsCurrentSpan(fn) all work, as does the full three-argument form. Omitting the name asks for the conventions’ {operation} {target} name; see startSpan.

Type Parameters

Parameters

Returns

Promise<T>

startGeneration()

Call Signature

function startGeneration(name, options?): Generation;

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

The name is optional; omitted, the span is named {operation} {model}.

Parameters

Returns

Generation

Call Signature

function startGeneration(options?): Generation;

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

The name is optional; omitted, the span is named {operation} {model}.

Parameters

Returns

Generation

startSpan()

Call Signature

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.

Because it never becomes current, an AGENT span created here opens no agent scope: a TOOL span started while it is open falls back to the configured agent name for gen_ai.agent.name rather than naming this one. Use startAsCurrentSpan (or observe) where that matters.

The name is optional: omit it and the span is named the way the GenAI conventions say to, {operation} {target} — execute_tool get_weather, invoke_agent planner, retrieval docs-index — from the attributes it is being created with. A name you pass always wins.

Parameters

Returns

Observation

Call Signature

function startSpan(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.

Because it never becomes current, an AGENT span created here opens no agent scope: a TOOL span started while it is open falls back to the configured agent name for gen_ai.agent.name rather than naming this one. Use startAsCurrentSpan (or observe) where that matters.

The name is optional: omit it and the span is named the way the GenAI conventions say to, {operation} {target} — execute_tool get_weather, invoke_agent planner, retrieval docs-index — from the attributes it is being created with. A name you pass always wins.

Parameters

Returns

Observation

withSession()

Call Signature

function withSession<T>(fn): T;

Scope every span started inside fn to one session id.

Pass the application’s own id (a conversation id, a job id) to correlate with it; omit it to mint a fresh UUID for the scope. Either way the scope’s id is passed to the callback, so it can be logged or handed to the next turn. Nested scopes override outer ones, and an active scope overrides the init({ sessionId }) default.

There is deliberately no process-wide auto-generation: without an id the backend groups each trace as its own session, which stays true in a server handling many users, while an auto-minted global id would merge every user into one. A generated id is only ever scoped to an explicit callback, where “this is one session” is the caller’s own claim.

await withSession(conversationId, async () => {
  await handleTurn(message) // every span of the turn carries session.id
})

Type Parameters

Parameters

Returns

T

Call Signature

function withSession<T>(sessionId, fn): T;

Scope every span started inside fn to one session id.

Pass the application’s own id (a conversation id, a job id) to correlate with it; omit it to mint a fresh UUID for the scope. Either way the scope’s id is passed to the callback, so it can be logged or handed to the next turn. Nested scopes override outer ones, and an active scope overrides the init({ sessionId }) default.

There is deliberately no process-wide auto-generation: without an id the backend groups each trace as its own session, which stays true in a server handling many users, while an auto-minted global id would merge every user into one. A generated id is only ever scoped to an explicit callback, where “this is one session” is the caller’s own claim.

await withSession(conversationId, async () => {
  await handleTurn(message) // every span of the turn carries session.id
})

Type Parameters

Parameters

Returns

T

withUser()

function withUser<T>(userId, fn): T;

Scope every span started inside fn to one end user.

Pass the application’s own identifier for the person the request serves. Prefer an opaque id over an email: it is stored on every span and shown in the console. When only sensitive identifiers exist, hash them first (OTel’s user.hash / enduser.pseudo.id guidance). Nested scopes override outer ones. The id is passed to the callback so it can be logged alongside the work.

await withUser(request.userId, async () => {
  await handle(request) // every span of the request carries user.id
})

Type Parameters

Parameters

Returns

T

withWorkspace()

function withWorkspace<T>(alias, fn): T;

Scope every span started inside fn to one workspace destination.

alias names a workspace registered via init({ workspaces }) or registerWorkspace(); the scope’s spans are exported with that workspace’s API key. Scopes nest and follow async continuations the way all OTel context does, but a trace must stay inside one workspace: enter the scope at a request boundary, before the root span starts.

await withWorkspace("acme", async () => {
  await handle(request) // every span of the request lands in acme's workspace
})

Type Parameters

Parameters

Returns

T

Generation

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

Extends

• Observation

Constructors

Constructor

new Generation(span, provider?): Generation;

The provider passed at creation; drives the Anthropic input-token summing in setUsage. A bare new Generation(span) has none and never sums.

Parameters

Returns

Generation

Overrides

Observation.constructor

Methods

[dispose]()

dispose: void;

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

Returns

void

Inherited from

Observation.[dispose]

end()

end(): void;

Ends the span after recording the context sizes; idempotent like the base.

Returns

void

Overrides

Observation.end

recordException()

recordException(error): this;

Record an error on the span, set ERROR status and error.type. 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.

error.type is Conditionally Required by the GenAI conventions on every span that ends in an error, and every helper’s throw path funnels through here, so this is the one place that sets it. The error’s name or class (see errorType), never the message: it must stay low-cardinality and free of echoed content.

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

Parameters

Returns

this

Inherited from

Observation.recordException

recordFirstToken()

recordFirstToken(): this;

Mark the arrival of the first streamed token. Records the gen_ai.first_token event (the timestamp the backend derives TTFT from) and, per the GenAI conventions, the derived gen_ai.response.time_to_first_chunk (seconds since span creation) plus gen_ai.request.stream = true: a first chunk arriving is what tells the SDK the request streamed. Idempotent: only the first call records, 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;

Set an arbitrary attribute. Primitives and homogeneous primitive arrays are passed through as the OTel values they are; objects are JSON-encoded and bounded; undefined and null set nothing, since “no value” is not an empty string.

Parameters

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

Returns

this

setInput()

setInput(value): this;

Record the request messages (gen_ai.input.messages), normalised to the GenAI {role, parts} shape like the Python SDK does: bare strings, OpenAI dicts (including tool_calls and tool responses) and multimodal content lists are all accepted. Bare strings default to the user role.

Parameters

Returns

this

Overrides

Observation.setInput

setModel()

setModel(model): this;

Parameters

Returns

this

setOutput()

setOutput(value): this;

Record the response messages (gen_ai.output.messages); bare strings default to assistant.

Parameters

Returns

this

Overrides

Observation.setOutput

setResponseId()

setResponseId(id): this;

The provider’s identifier for this completion (gen_ai.response.id) — OpenAI’s id, Anthropic’s id, and so on. A post-call setter and not a creation option for the reason setModel is one: the value arrives WITH the response, so no span can carry it at creation and no pending snapshot can either. Recorded verbatim; it is an opaque provider string, and it is not content, so it survives captureContent: false.

Parameters

Returns

this

setRetrievedDocuments()

setRetrievedDocuments(documents): this;

Record what a retrieval returned, as gen_ai.retrieval.documents.

The conventions define this as an array of objects, each with an optional id and an optional score. Identifiers and relevance, never document text, which is why it is not treated as content: it survives captureContent: false the way token counts do. Put the retrieved text in setOutput if you want it captured, and masking applies to it there.

Unlike dataSourceId and topK, which describe the request and are passed at span creation, this is only knowable once the search has run, so it never reaches a pending snapshot.

Parameters

Returns

this

Inherited from

Observation.setRetrievedDocuments

setToolDefinitions()

setToolDefinitions(tools): this;

The request’s tool/function definitions (gen_ai.tool.definitions). Serialized verbatim, in whatever shape the provider request used (OpenAI nests each tool under function, Anthropic uses top-level name/input_schema) — no normalization, so what is recorded is exactly what the model was shown. Definitions are content, not identity: they are masked/stripped under captureContent: false like messages are.

Parameters

Returns

this

setUsage()

setUsage(usage): this;

Token usage (gen_ai.usage.*). Pass provider-reported values as-is; never pre-add anything. Per the GenAI conventions, inputTokens is the total including cached tokens (the cache counts are subsets of it). Anthropic’s API reports input_tokens excluding the cache counts, and the conventions require the instrumentation to do the summing, so when the generation’s provider is "anthropic" the emitted total is inputTokens plus both cache counts. Every other provider is recorded verbatim.

Parameters

Returns

this

Properties

Observation

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

Extended by

• Generation

Constructors

Constructor

new Observation(span): Observation;

Parameters

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;

Record an error on the span, set ERROR status and error.type. 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.

error.type is Conditionally Required by the GenAI conventions on every span that ends in an error, and every helper’s throw path funnels through here, so this is the one place that sets it. The error’s name or class (see errorType), never the message: it must stay low-cardinality and free of echoed content.

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

Parameters

Returns

this

setAttribute()

setAttribute(key, value): this;

Set an arbitrary attribute. Primitives and homogeneous primitive arrays are passed through as the OTel values they are; objects are JSON-encoded and bounded; undefined and null set nothing, since “no value” is not an empty string.

Parameters

Returns

this

setInput()

setInput(value): this;

Parameters

Returns

this

setOutput()

setOutput(value): this;

Parameters

Returns

this

setRetrievedDocuments()

setRetrievedDocuments(documents): this;

Record what a retrieval returned, as gen_ai.retrieval.documents.

The conventions define this as an array of objects, each with an optional id and an optional score. Identifiers and relevance, never document text, which is why it is not treated as content: it survives captureContent: false the way token counts do. Put the retrieved text in setOutput if you want it captured, and masking applies to it there.

Unlike dataSourceId and topK, which describe the request and are passed at span creation, this is only knowable once the search has run, so it never reaches a pending snapshot.

Parameters

Returns

this

Properties

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

GenerationOptions

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

Properties

InitOptions

Options accepted by init, extending the shared configuration.

Extends

• RiusOptions

Properties

ObserveOptions

Options for observe.

Properties

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

SpanOptions

Options for startSpan and startAsCurrentSpan.

Properties

GenerationBody()

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

The body of a scoped generation.

Type Parameters

Parameters

Returns

Promise<T> | T

Mask()

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

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

Parameters

Returns

unknown

SpanBody()

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

The body of a scoped span.

Type Parameters

Parameters

Returns

Promise<T> | T

WorkspaceExporterFactory()

type WorkspaceExporterFactory = (apiKey) => SpanExporter;

Workspaces: route spans from one process to per-customer destinations.

One client, one provider, one batch pipeline; the destination is a context-scoped property. withWorkspace(alias, fn) sets an OTel context key (exactly like withSession), WorkspaceSpanProcessor stamps it as a transient attribute at span start, and RoutingSpanExporter partitions each export batch by that attribute, strips it, and forwards every partition to the exporter registered for its alias. Spans started outside any scope go to the default destination.

Because the alias rides OTel context, everything started in scope routes together: observe wrappers, generations, sessions, and spans created by auto-instrumentation. That is the property a second client could never give, which is why this SDK has no scoped-client mode at all.

Two rules the design enforces or warns about:

• The routing attribute never reaches the wire. The destination’s API key is what tells the backend which workspace a span belongs to; the alias is process-local configuration, so the exporter strips it before delegating.
• One trace, one workspace. The backend derives the workspace from the API key per request, so a trace split across scopes would come apart. Starting a span under a different alias than its parent’s logs a warning; switch workspaces at request boundaries, not inside a trace.

Parameters

Returns

SpanExporter

SpanKind

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

Enumeration Members

VERSION

const VERSION: "1.0.0" = "1.0.0";