Skip to Content

How do I move my instrumentation code from Helicone to Rius?

Rius moves your Helicone instrumentation into the Rius SDK, which traces your client inside your process and maps sessions, users and properties to Rius equivalents. You add rius.init(), then replace the Helicone-* headers with Rius sessions, users and span attributes. Gateway features such as caching, rate limits, retries and fallbacks have no counterpart. The full walkthrough is in Migrate from Helicone.

How it works

Helicone is mainly a proxy. Your client sends each request through a Helicone base URL, and Helicone-* request headers configure what gets logged. Rius is OpenTelemetry-based. The Rius SDK patches your provider client in your process and exports a span for each step, so nothing sits between your code and the provider.

Here is how each Helicone concept maps:

  • Request becomes a generation, an LLM span with model, tokens and messages. Auto-instrumentation creates one per call.
  • Session id (Helicone-Session-Id) becomes rius.session(id), which stamps session.id on every span in scope.
  • Session path (Helicone-Session-Path) becomes span nesting. A span started inside another span is its child, so the tree comes from your call structure, not a path string.
  • Session name (Helicone-Session-Name) has no separate field. Name the span that wraps the work, or set an attribute.
  • User id (Helicone-User-Id) becomes rius.user(id), which stamps user.id. Each user appears on the Users page.
  • Custom properties (Helicone-Property-*) become span attributes, or resource attributes for values that describe the whole process.
  • Omit request and response becomes capture_content=False, which strips prompts and completions at export while metadata still flows.
  • Cost is computed by Rius from the model and token counts. You send no cost value.

Two things have no counterpart. Gateway features (caching, rate limits, retries, fallbacks, a unified API) stay with whatever serves them today, because Rius is not a gateway. Prompts, datasets, scores, feedback and evals are not offered either. Existing Helicone history also stays in Helicone, because Rius starts from the first span you send.

Set it up

  1. Install the SDK with the integrations for your providers, set your key and call init() once at startup. Once you drop the Helicone base URL and Helicone-Auth header, the client goes straight to the provider, as below. To compare both tools first, keep them for now (step 5). The Migrate to Rius overview covers the other paths.

    pip install "glassflow-rius[openai,anthropic]"
export RIUS_API_KEY="ri_..."
    import rius
from openai import OpenAI
 
rius.init(service_name="my-agent")  # reads RIUS_API_KEY
openai_client = OpenAI()           # default base URL, OPENAI_API_KEY

  2. If you used Helicone’s async logger, delete it and do not run both in one process. Both register the process-wide OpenTelemetry tracer provider, OpenTelemetry keeps only the first registration, and calls reach only one tool. To compare backends, run each in a separate service or deploy.

  3. Add session and user scopes for the values you send as headers. Remove the headers themselves at cutover (step 6), so Helicone keeps its sessions while you compare. Nest a span for each level of your old session path.

    with rius.session(session_id):
    with rius.user(request.user_id):
        with rius.start_as_current_span("support_ticket") as span:
            span.set_attribute("app.ticket_id", ticket_id)
            response = openai_client.chat.completions.create(
                model="gpt-4o-mini", messages=messages,
            )

    In TypeScript the scopes are withSession and withUser, and you await rius.ready after init() before the first call.

  4. Move deployment-level properties such as app version or region onto the resource with the standard OpenTelemetry variable. Keep each environment in its own workspace with its own API key.

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

  5. If you keep the Helicone gateway for now, leave its base URL and headers in place. The Rius integrations patch the client library, not the network path, so calls are traced either way. Use plain model names such as gpt-4o-mini, not the gateway’s gpt-4o-mini/openai form, or calls show tokens but no cost.

  6. Verify one call end to end. The trace appears under your service_name, the generation shows model and token counts, and cost appears. Then remove the Helicone base URL, headers and logger, and revoke the Helicone key once nothing sends to it.

What you get

  • Traces with the full tree of agent, tool, retrieval and model steps, not LLM requests only.
  • Sessions and per-user views from the same scopes you set in code, with failures, error rate and cost for each user.
  • Cost per call, computed by Rius from the model and tokens as a list-price estimate in US dollars.
  • Filterable span and resource attributes in place of Helicone-Property-* headers.
  • A side-by-side period. With the gateway kept, every call is logged by Helicone and traced by Rius, so you can compare counts, tokens and cost before cutting over. During that period Rius cost runs higher than Helicone’s by your cache-hit share, because a response Helicone serves from its cache is priced from its tokens like any other call.
  • Alerts and an MCP server so your coding agent can query production traces.

The full cutover checklist is in Migrate from Helicone.

When something else fits

  • If caching, rate limits, retries or fallbacks are load-bearing, keep the Helicone gateway and add Rius next to it. Replace the gateway as a separate project, if at all.
  • If you depend on prompt management, scores, feedback, datasets, evals or moderation, keep those workflows in your current tool. Rius does not offer them.
  • If you use the AI Gateway with Helicone-managed provider keys or credits, switch to your own provider keys first. Rius never holds provider keys.

Still stuck? Get help

Last updated on
Quickstart