Migrate from Helicone to Rius

Helicone and Rius capture LLM calls in different ways. Helicone is mainly a proxy: your client sends every request through a Helicone base URL, and Helicone logs it on the way through, with features configured by Helicone-* request headers. Rius is OpenTelemetry-based: the Rius SDK instruments your LLM client inside your process and exports spans (one record per step, such as an LLM call), so nothing sits between your code and the provider.

Migrating is a small code change: add the Rius SDK, point the client back at the provider if you no longer need the gateway, and move the values you sent as Helicone headers onto Rius sessions, users and span attributes. This guide maps the concepts, walks the paths, and ends with a cutover checklist.

Why migrate from Helicone to Rius

Rius is agent observability. You get:

• traces with the full tree of agent, tool, retrieval and model steps, not LLM requests only
• sessions, per-user views and server-side cost
• alerts
• with the Rius SDK, which agent processes are alive, and, with partial spans turned on, runs still in progress
• an MCP server so your coding agent can query production traces

What Helicone offers beyond observability is covered in what does not carry over.

Concept mapping: Helicone vs Rius

Choose your path

• You call through the Helicone proxy or AI Gateway (oai.helicone.ai, anthropic.helicone.ai, ai-gateway.helicone.ai, or a Helicone-Auth header): instrument with the Rius SDK, then decide whether to keep the gateway in front of the provider.
• You use Helicone’s async logger (helicone-async or @helicone/async): replace the logger with the Rius SDK. Both instrument your client in process, so the swap is one call.

Path A: instrument your client with the Rius SDK

Install the SDK with the integrations for the providers you call. In Python the extras install the instrumentation. In TypeScript you install the instrumentation packages next to the SDK: the @arizeai/openinference-instrumentation-* packages are the OpenInference instrumentations the Rius TypeScript SDK attaches for each provider.

pip install "glassflow-rius[openai,anthropic]"
export RIUS_API_KEY="ri_..."

npm install @glassflow-ai/rius @opentelemetry/api \
  @arizeai/openinference-instrumentation-openai \
  @arizeai/openinference-instrumentation-anthropic
export RIUS_API_KEY="ri_..."

Point the client back at the provider

With Helicone, the provider client carries a Helicone base URL and an auth header. With Rius, the client is the provider’s default one, and init() traces every call it makes:

# Before: through the Helicone proxy
import os
from openai import OpenAI
from anthropic import Anthropic
 
openai_client = OpenAI(
    base_url="https://oai.helicone.ai/v1",
    default_headers={"Helicone-Auth": f"Bearer {os.environ['HELICONE_API_KEY']}"},
)
anthropic_client = Anthropic(
    base_url="https://anthropic.helicone.ai",
    default_headers={"Helicone-Auth": f"Bearer {os.environ['HELICONE_API_KEY']}"},
)

# After: direct to the provider, traced by Rius
import rius
from openai import OpenAI
from anthropic import Anthropic
 
rius.init(service_name="my-agent")  # reads RIUS_API_KEY
 
openai_client = OpenAI()        # default base URL, OPENAI_API_KEY
anthropic_client = Anthropic()  # default base URL, ANTHROPIC_API_KEY

// After: direct to the provider, traced by Rius
import { init } from '@glassflow-ai/rius'
import OpenAI from 'openai'
import Anthropic from '@anthropic-ai/sdk'
 
const rius = init({ serviceName: 'my-agent' }) // reads RIUS_API_KEY
await rius.ready // wait until instrumentation is attached before the first call
 
const openai = new OpenAI()       // default base URL, OPENAI_API_KEY
const anthropic = new Anthropic() // default base URL, ANTHROPIC_API_KEY

Each call becomes a generation with the model, input and output tokens (including cache reads and writes), and the messages; Rius computes cost from the model and tokens. Calling a provider other than OpenAI or Anthropic? Check the integrations list, or trace the call as a manual generation.

Keep the gateway and run side by side

If you rely on gateway features, such as caching, rate limits or fallbacks, leave the Helicone base URL and headers in place and add rius.init() anyway. The Rius integrations patch the client library in your process, not the network path, so calls are traced whatever base URL the client uses. This is also the side-by-side setup: every call is logged by Helicone on the network path and traced by Rius in your process, so you can compare request counts, token totals and cost on the same traffic, then remove the Helicone base URL when you are ready.

Two differences when you keep the gateway:

• Cache hits: Rius instruments the client in your process, so a response Helicone serves from its cache is recorded like any other call: a generation with the token counts the response carries, priced from those tokens at the provider’s rates. During side by side, Rius cost is higher than Helicone’s by your cache-hit share.
• Model names: use plain model names (gpt-4o-mini), not the gateway’s gpt-4o-mini/openai form, or calls show tokens but no cost.

Path B: replace the Helicone async logger

Helicone’s async logger instruments your provider client in process and sends the calls to Helicone without the proxy. The Rius SDK works the same way, so the swap is one call. Install the SDK as in Path A, then:

# Before: Helicone async logger
from helicone_async import HeliconeAsyncLogger
 
logger = HeliconeAsyncLogger(api_key=HELICONE_API_KEY)
logger.init()

# After: Rius SDK
import rius
 
rius.init(service_name="my-agent")  # reads RIUS_API_KEY

// Before: Helicone async logger
import { HeliconeAsyncLogger } from '@helicone/async'
import OpenAI from 'openai'
 
const logger = new HeliconeAsyncLogger({
  apiKey: process.env.HELICONE_API_KEY,
  providers: { openAI: OpenAI },
})
logger.init()

// After: Rius SDK
import { init } from '@glassflow-ai/rius'
 
const rius = init({ serviceName: 'my-agent' }) // reads RIUS_API_KEY
await rius.ready // wait until instrumentation is attached before the first call

Replace logger.set_properties(...) (withProperties in TypeScript) with the session, user and attribute equivalents in map Helicone headers and properties. Remove the Helicone logger rather than running both in one process: both register the process-wide OpenTelemetry tracer provider, OpenTelemetry keeps only the first registration, and the instrumented calls reach only one of the two tools. To compare the two backends, run the logger in one service and the Rius SDK in another, or compare a deploy on each.

Map Helicone headers and properties

These replace the Helicone-* headers (or the async logger’s properties), whichever path you took.

Sessions

Helicone groups requests with Helicone-Session-Id and arranges them with Helicone-Session-Path. In Rius you scope a session around the work, and the tree comes from how your spans nest:

# Before: Helicone session headers on each request
response = openai_client.chat.completions.create(
    model="gpt-4o-mini",
    messages=messages,
    extra_headers={
        "Helicone-Session-Id": session_id,
        "Helicone-Session-Path": "/ticket/answer",
        "Helicone-Session-Name": "Support ticket",
    },
)

# After: a Rius session scope and a parent span
with rius.session(session_id):
    with rius.start_as_current_span("support_ticket"):
        response = openai_client.chat.completions.create(
            model="gpt-4o-mini", messages=messages,
        )

// After: a Rius session scope and a parent span
import { withSession, startAsCurrentSpan } from '@glassflow-ai/rius'
 
await withSession(sessionId, () =>
  startAsCurrentSpan('support_ticket', async () => {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages,
    })
  }),
)

Every span started inside the scope, including the auto-instrumented LLM call, carries session.id. To keep the structure of a Helicone-Session-Path such as /ticket/answer, nest spans the same way: a ticket span with an answer span started inside it. Sessions covers scopes and the process-wide default.

Users

Helicone-User-Id maps to a user scope:

with rius.user(request.user_id):
    handle(request)  # every span of the request carries user.id

import { withUser } from '@glassflow-ai/rius'
 
await withUser(request.userId, async () => {
  await handle(request) // every span of the request carries user.id
})

Users appear on the Users page and as a user filter on the trace list.

Custom properties

A Helicone-Property-* header tags one request. In Rius, tags are span attributes. How you carry them over depends on what the property describes:

• Per request (a ticket id, a conversation, a feature): set it on the span that wraps the work.

  with rius.start_as_current_span("support_ticket") as span:
      span.set_attribute("app.ticket_id", ticket_id)
      span.set_attribute("app.feature", "auto-reply")
      response = openai_client.chat.completions.create(...)

  The trace list finds the trace when any of its spans carries the value.

• Per deployment (app version, region): put it on the resource (the attributes that describe the process, set with the standard OpenTelemetry OTEL_RESOURCE_ATTRIBUTES variable), so every span from the process carries it. Keep each environment (production, staging) in its own workspace with its own API key rather than tagging it here.

  export OTEL_RESOURCE_ATTRIBUTES="service.version=1.4.2,app.region=eu"

Filter on either kind in the trace list with Add filter; see search and filter, and declare an attribute with a type to filter it numerically.

What does not carry over from Helicone

Rius is an observability platform, not a gateway, and today it has no equivalent for:

• Gateway features: no proxy, so no response caching, no rate limits, no automatic retries, no provider or model fallbacks, and no unified API across providers. If you depend on these, keep the Helicone gateway or move them to another gateway or your own client code. Rius traces the calls either way.
• Provider key management and credits: Rius never holds your provider keys and never bills for model usage. You call providers with your own keys.
• Prompt management: no versioned prompts, prompt deployment or prompt playground. Prompt content on spans is captured and inspectable, but there is no registry.
• Scores, feedback, datasets and evals: no score or feedback objects on traces, no curated datasets, and no eval runs.
• Security and moderation: no prompt-injection detection or moderation layer, since those run in the request path.
• Property and product analytics: attributes are filterable, but there is no cost or metric breakdown per custom property, and no active-user, retention or cohort analytics.
• Self-hosting: Rius is a hosted service only.
• Historical data: existing traces stay in Helicone; Rius starts from the first span you send it.

Helicone to Rius cutover checklist

1. Create a Rius workspace and API key (quickstart). New organizations start with a free trial (30 days or 500,000 spans, whichever comes first), then a paid plan; see Plans and billing.
2. Install the Rius SDK with your providers’ integrations and call rius.init() at startup (installation).
3. Keep both backends on the same traffic for now. With the proxy or AI Gateway, keep the Helicone base URL and headers (side by side). With the async logger, run it and the Rius SDK in separate services or deploys (Path B).
4. Verify one call end to end in Rius: the trace appears under the agent named by the service_name you passed to rius.init() (serviceName in TypeScript), the generation shows model and token counts, and cost appears.
5. Replace Helicone-Session-Id with rius.session(), Helicone-User-Id with rius.user() (withSession and withUser in TypeScript), and Helicone-Property-* with span or resource attributes. Check the session and user show on the trace.
6. Compare both backends on real traffic for a few days: request and LLM call counts, token totals, cost.
7. Decide what happens to gateway features you use. Keep the gateway, or move caching, retries and fallbacks elsewhere first.
8. Move anything that reads from Helicone (dashboards, alerts, the query API) to the Rius equivalents, or deliberately leave it behind.
9. Remove the Helicone base URL, Helicone-* headers and async logger, and revoke the Helicone API key once nothing sends to it.

Frequently asked questions