How do I install the Rius SDK for TypeScript?

Rius installs for TypeScript with one npm command, npm install @glassflow-ai/rius @opentelemetry/api, followed by a single init call with your API key and a service name. The package is @glassflow-ai/rius and needs Node 18 or newer. Integrations for libraries such as OpenAI are separate optional packages that init turns on when it finds them.

How it works

• Package. @glassflow-ai/rius is MIT licensed and needs Node 18 or newer. It does not bundle @opentelemetry/api. That is a peer dependency, so you install it next to the SDK at a version that satisfies ^1.9.0.
• Integrations are peer packages, not extras. A plain install of the SDK patches nothing. You install the instrumentation package for each library you use, and init enables whatever it finds.
• Startup is asynchronous for integrations. init returns right away. Auto-instrumentation attaches a moment later, so await client.ready if it must be in place before your first span. It resolves with the names that attached and never rejects.
• Where settings come from. Explicit options win over environment variables, which win over defaults. Every option is optional, and every environment variable starts with RIUS_.
• No flush on exit. The TypeScript SDK does not export queued spans when the process ends, so a short script must call shutdown itself.

The full reference is on the installation and configuration page.

Set it up

1. Install the SDK and its peer dependency:

npm install @glassflow-ai/rius @opentelemetry/api

2. Install the packages for the libraries you call. Each line is only needed if you use that library:

npm install @arizeai/openinference-instrumentation-openai   # OpenAI
npm install @modelcontextprotocol/sdk                       # MCP tool calls
npm install @ai-sdk/otel                                    # Vercel AI SDK, ai 7 only

The Vercel AI SDK on ai 7 also needs Node 22 or newer. On ai 5 and 6 you install nothing extra and set experimental_telemetry with isEnabled true on each call. See Integrations for every supported library.

3. Get an API key from the Rius console. Keys start with ri_. Older keys start with gf_ and keep working. You can pass the key as apiKey or set RIUS_API_KEY.

4. Call init once, as early as possible in your process:

import { init } from '@glassflow-ai/rius'
 
const client = init({
  apiKey: 'ri_...',
  serviceName: 'my-agent',
})
 
// init() is synchronous. Auto-instrumentation attaches asynchronously, so await
// `ready` if you need it in place before your first span. It resolves with the
// names that attached, and never rejects.
const attached = await client.ready

5. In a short script, export queued spans before the process exits:

await client.shutdown()

6. Set the options that matter for your agent:

• serviceName (RIUS_SERVICE_NAME): the name you use to find your agent in filters, analytics and cost breakdowns. It defaults to unknown_service, so always set it. Keep it constant across replicas and deploys, and keep version numbers out of it.
• serviceVersion (RIUS_SERVICE_VERSION): the build or release this process runs.
• mainAgentVersion (RIUS_MAIN_AGENT_VERSION): the version of the agent definition, meaning its prompt, tools and policy. It is independent of serviceVersion.
• agentName (RIUS_AGENT_NAME): how instances group in the Agents view. It defaults to the service name.
• captureContent (RIUS_CAPTURE_CONTENT): set it to false to strip prompt and response content at export while metadata still flows.
• sampleRate (RIUS_SAMPLE_RATE): head sampling of root traces, 1.0 by default.
• heartbeat (RIUS_HEARTBEAT): on by default and needs credentials. It lets the Agents view know the process is alive.
• disabled (RIUS_DISABLED): a kill switch that attaches no exporter.
• endpoint (RIUS_ENDPOINT): defaults to https://ingest.eu.console.rius-glassflow.com, and traces post to that base plus /v1/traces.

If init runs twice with a global client active, the second call logs a warning and returns the existing client. To reconfigure, await client.shutdown() first. A pnpm app on a host that traces files, such as a Vercel function, may also need the instrumentModules option.

What you get

• Spans for your LLM and tool calls arrive in Rius from the libraries you installed, without manual span code.
• Every span carries your service.name, so you can filter, analyze and break down cost by agent.
• Rius computes cost and time to first token from those spans. You never send a cost value.
• With the heartbeat on, the Agents view shows each process as an instance of your agent.
• Content capture, sampling and a kill switch are one option or environment variable each.

When something else fits

• If your service is written in Python, install glassflow-rius instead. The installation page covers both SDKs.
• If you already run an OpenTelemetry SDK or collector, you can send traces to Rius without the Rius SDK.

Related